Migrating a Catalog File to the Latest CDF Version
This page describes changes involved in each version of the Fire TV CDF schema beginning with v1.0, and gives a series of steps to follow to update a catalog file to the latest version.
- Migration Overview
- Migrating from CDF v1.0 to v1.1
- Migrating from CDF v1.1 to v1.2
- Migrating from CDF v1.2 to v1.3
Migration Overview
Amazon occasionally updates its Catalog Data Format (CDF) XML schema to accept new metadata, remove unused information, or clarify the catalog structure. These changes do not cause existing CDF files to become invalid, but some data in older tags might be ignored or used in new ways, and deprecation warnings will appear in the Catalog Ingestion Report (explained in Verify Your Catalog File.
How and where you make these changes depends on how you create your catalog file. If you have code that pulls the information from a database and transforms it into a catalog file, you'll need to change the transformation code. If your database is structured to match the CDF, you'll need to alter the fields of the database itself.
Upgrade your CDF file in stages (v1.0 to v1.1, v1.1 to v1.2, etc.), accounting for each version change in turn. It is a linear progression that varies only in where you start. If you don't know which CDF version your file uses, start from the beginning. The changes between versions are mostly additions of new optional elements, so simply adapting your current file as-is to a new schema version requires very few alterations, generally just one or two per version.
Some XML elements must be placed in your catalog file in a specific order defined by the CDF XSD file. An element that's out of order makes the catalog file invalid. Refer to the appropriate XSD file if you have any question about element order.
Also look at the downloadable example CDF files (ZIP).
This topic assumes that you are familiar with XML and the CDF schema.
Migrating from CDF v1.0 to v1.1
Here are the differences between CDF v1.0 and v1.1:
Item | Type | Change | Notes |
---|---|---|---|
WorkType.Source |
Element | Added | Optional. Specifies the origin of the work. Accepted values are:
|
WorkType.AdultProduct |
Element | Deprecated | This value is no longer used and the element should be removed. Adult content can be identified through the ContentRatings element. In Japan, you can use the JP_Require18PlusAge Confirmation element added in v1.2. |
To update a CDF file from v1.0 to v1.1
- Remove all instances of WorkType.AdultProduct.
- Optional: Add the Source element to all work elements (Movie, TvShow, TvEpisode, TvSpecial, TvSeason, MiniSeries, MiniSeriesEpisode, and Extra). Placement of the Source element varies by work type; see the XSD for correct placement.
Migrating from CDF v1.1 to v1.2
Here are the differences between CDF v1.1 and v1.2:
Item | Type | Change | Notes |
Catalog.version |
Attribute | Added | Optional. Use this attribute so that others who work with the file will know which CDF version it was created against. Accepted values are FireTv-v1.2 and FireTv-v1.3 |
OfferType.LaunchDetails | Element | Added | Optional. Includes these child elements in the given order.
|
OfferType.Quality |
Element | Deprecated/Moved | This element is now a child element of OfferType.LaunchDetails (see above). It can be moved to the new location otherwise unchanged. |
CustomerRating.Count |
Element | Added | Optional. Allows you to specify the number of ratings from which the final rating was averaged. Placed as the last element under CustomerRating. |
JP_Require18PlusAgeConfirmation |
Element | Added | Optional. Only used by Japanese content providers. Accepted values are true and false. When true, viewers of this content in Japan are presented with a dialog in which they must confirm that their age is 18 or above, in accordance with Japanese law. This element should, at a minimum, be added it to those works that Japanese regulators regard as not to be viewed by anyone under 18. This element’s placement depends on the work type. |
CastMember.Role |
Element | Now optional | This element, which specifies the name of the character played by the cast member, was required in v1.1 but can now be omitted. |
To update a CDF file from v1.1 to v1.2
- For any SubscriptionOffer, FreeOffer, PurchaseOffer, or RentalOffer that includes a Quality element:
- Add a LaunchDetails element as the last element in each offer.
-
Move the Quality element from its current location to the LaunchDetails element.
Example:
Before
<FreeOffer> <Quality>HD</Quality> ... </FreeOffer>
After
<FreeOffer> ... <LaunchDetails> <Quality>HD</Quality> </LaunchDetails> </FreeOffer>
-
Optional. For any SubscriptionOffer, FreeOffer, PurchaseOffer, or RentalOffer that didn't include a Quality element, add a LaunchDetails element as the last element for each. Add as much of the optional Quality, AudioLanguage, Subtitle, and LaunchId information as you have.
Example:
<FreeOffer> ... <LaunchDetails> <Quality>HD</Quality> <AudioLanguage>en-us</AudioLanguage> <Subtitle>en</Subtitle> <Subtitle>es</Subtitle> <LaunchId>tt123456_HD_en-us</LaunchId> </LaunchDetails> <LaunchDetails> <Quality>HD</Quality> <AudioLanguage>es-mx</AudioLanguage> <Subtitle>en</Subtitle> <Subtitle>es</Subtitle> <LaunchId>tt123456_HD_es-mx</LaunchId> </LaunchDetails> </FreeOffer>
-
Optional, but recommended. Add the version attribute, set to FireTv-v1.2, to the existing Catalog element at the top of your CDF file.
Example:
<Catalog xmlns="http://www.amazon.com/FireTv/2014-04-11/ingestion" version="FireTv-v1.2">
- Optional. If you have CustomerRating elements in your catalog, add a Count element as the last element in CustomerRating. This value should be updated whenever you update the CustomerRating.Score value. How you collect and track that information is up to you.
-
Optional for providers of content to Fire TV in Japan. Add a JP_Require18PlusAgeConfirmation element to at least those works for which it is set to true. Consult the XSD file for the element's placement, as it varies by work type.
Example:
<Movie> ... <JP_Require18PlusAgeConfirmation>true</JP_Require18PlusAgeConfirmation> <ReleaseDate>1959-05-13T04:36:00</ReleaseDate> </Movie>
Migrating from CDF v1.2 to v1.3
Here are the differences between CDF v1.2 and v1.3.
Item | Type | Change | Notes |
---|---|---|---|
MiniSeries |
Element | Added | A mini-series is loosely defined as a TV show limited to a small number of ordered episodes, without seasons. |
MiniSeriesEpisode |
Element | Added | An individual episode in a mini-series, used in the same manner as a TvEpisode in relation to a TvShow. |
Extra |
Element | Added | Supplementary material, often to accompany a work. Accepted values are:
|
ReleaseInfo |
Element | Deprecated/Moved | This element contained two child elements:
|
Movie.ReleaseDate |
Element | Added | Optional. This is the new location of the deprecated Movie.ReleaseInfo.ReleaseDate . See the ReleaseInfo entry above for details. |
TvShow.ReleaseDate |
Element | Added | Optional. This is the new location of the deprecated TvShow.ReleaseInfo.ReleaseDate . See the ReleaseInfo entry above for details. |
TvEpisode.OriginalAirDate |
Element | Added | Optional. This is the new location of the deprecated TvEpisode.ReleaseInfo.ReleaseDate . See the ReleaseInfo entry above for details. |
TvSpecial.OriginalAirDate |
Element | Added | Required. This is the new location of the deprecated TvSpecial.ReleaseInfo.ReleaseDate . See the ReleaseInfo entry above for details. |
TvSpecial.ShowID |
Element | Added | Optional. This element allows you to attach a special to a specific show, in the situation where the special was an event outside of the regular run of a series. This value must match a TvShow.ID value in your catalog. You cannot include both this value and TvSpecial.ShowTitle . |
TvSpecial.ShowTitle |
Element | Added | Optional. This element allows you to attach a special to a show not included in your catalog. The ShowTitle string isn’t required to match any title in your catalog. It is used to create the illusion of an attachment without the underlying structure. Use this value only when you cannot use ShowID. |
Works |
Element | Can now be empty | Previously this would have caused your catalog to be invalid. Now, an empty Works element has the effect of removing all of your content from Amazon Fire TV’s universal browse and search. |
WorkType.ID |
Element | Must now be at least one character in length | The element itself (a unique identifier for each work) was always required, but now it requires a value as well. Given that this is an extremely important piece of information, used in everything from tying episodes to seasons and shows to reporting where to find an error in the file, it should always be present and unique. |
To update a CDF file from v1.2 to v1.3
- Move the WorkType.ReleaseInfo.ReleaseDate element for all works to their new location. Change each date value to the XML dateTime format (YYYY-MM-DDThh:mm:ss). If you don't know the specific time that a work was released or aired, you can just use T00:00:00 for that portion of the string. The target ReleaseDate and OriginalAirDate elements are the last elements in their respective work types.
- Movie.ReleaseInfo.ReleaseDate moves to Movie.ReleaseDate
- TvShow.ReleaseInfo.ReleaseDate moves to TvShow.ReleaseDate
- TvEpisode.ReleaseInfo.ReleaseDate moves to TvEpisode.OriginalAirDate
- TvSpecial.ReleaseInfo.ReleaseDate moves to TvSpecial.OriginalAirDate
-
TvSeason.ReleaseInfo.ReleaseDate is no longer used so it requires no move
Example:
Before
<Movie> <Movie> ... <ReleaseInfo> <ReleaseDate>1959-05-13</ReleaseDate> </ReleaseInfo> ... </Movie> ... <TvSpecial> ... <ReleaseInfo> <ReleaseDate>1959-05-13</ReleaseDate> </ReleaseInfo> ... </TvSpecial>
After
<Movie> ... <ReleaseDate>1959-05-13T00:00:00</ReleaseDate> </Movie> ... <TvSpecial> ... <OriginalAirDate>1959-05-13T00:00:00</OriginalAirDate> </TvSpecial>
- Delete all instances of the
ReleaseInfo
element, including anyReleaseDate
andReleaseCountry
elements that they contain. -
Ensure that you don't have any empty
WorkType.ID
elements (it's unlikely). If you do, assign those works a unique ID.Example:
Before
<TvShow> <ID></ID> ... </TvShow>
After
<TvShow> <ID>ts-123456</ID> ... </TvShow>
- Optional. If you have existing content that would be more accurately described as a
MiniSeries
, move that information into the newMiniSeries
andMiniSeriesEpisode
work types. - Optional. If you have existing content that would be more accurately described as an
Extra
, move that information into the newExtra
work type. -
Optional, but recommended. Add or update the
version
attribute found in the Catalog element at the top of your CDF file toFireTv-v1.3
.Example:
<Catalog xmlns="http://www.amazon.com/FireTv/2014-04-11/ingestion" version="FireTv-v1.3">
- Optional, but recommended where applicable. Add either a
ShowID
(preferred) orShowTitle
element to eachTvSpecial
to connect that special to a show. For those specials that are standalone works, these elements can be omitted. - Optional. Add an OriginalAirDate element and value for each
TvSpecial
orTvEpisode
that didn't have aReleaseInfo.ReleaseDate
element. - Optional. Add a
ReleaseDate
element and value for each Movie or TvShow that didn't have aReleaseInfo.ReleaseDate
element.