Step 1: Create Your Catalog File

In this step, you will create a catalog file that contains the metadata (title, length, release year, etc.) for your app's media content (movies, TV shows, and extras). The catalog file must follow the Catalog Data Format (CDF) schema, which requires you to follow a specific XML structure for describing your media.

• Creating Your Catalog File
• General Catalog File Structure
• Common Elements for All Works
  • Common Optional Elements for All Works
  • A Note About Strings
• Elements Specific to the Work Type
• Tying Shows, Seasons, and Episodes Together
• Requirements for Box Art Images (ImageUrl)
  • Image requirements
• CDF FAQ
• Next Steps

Here is a video that will walk you through the process. For more details, continue reading the page below.

Creating Your Catalog File

Use an automated process to create the file by developing programmatic scripts that pull the information from your database and transform the data to a CDF-compliant catalog file.

In general, to create the file, you will need to first familiarize yourself with XML and its concepts as they relate to the catalog XSL schema — see the CDF Overview. You'll then download the CDF schema XSD file to understand the logic and rules at a more granular level. You can also use the code samples shown in the Element web pages as a starting point. As you create the file, consult the CDF reference documentation.

General Catalog File Structure

This section provides an overview of the structure of the CDF schema and its elements. Readers should have a good understanding of XML.

The top-level outline of a catalog file can be represented as:

<Catalog>
    <Partner> ... </Partner>
        <Works>
        ...
        </Works>
</Catalog>

Catalog (required) is the root element of all catalog files.

Partner (required) identifies you, the content provider.

Works (required) contains the bulk of the file: all of the movies and TV shows in your library, as much information as you choose to provide about each entry, and the offers that enable the user to view them.

The Works element can contain any number of child elements, each representing an individual work such as a movie or a TV show. If the Works element contains no child elements, we infer that all of your content is no longer available and we will remove it from our index.

The most common work type elements are as follows:

Movies are standalone elements. TV shows, TV seasons, and TV episodes are separate elements that are tied together by IDs. Extras can be standalone elements, but they can also be tied to other works. See Tying Shows, Seasons, and Episodes Together for details.

Common Elements for All Works

All of the work types listed above are built on a core of common elements, extended in each case with only 1-5 type-specific elements. Only a small subset of the common elements are required.

The outline of a work element can be represented as:

<_WorkType_> (such as <Movie> or <TvSeason>)
    <ID>
        <Title>
            <Offers>
</_WorkType_>

ID (required) is an identifier of your choosing for the work. Each work's ID must be unique within your catalog and it should never change as long as you offer that work. The ID element is also used in associating work elements, for instance to specify a TV episode as part of a TV show and season.

Title (required) is, of course, the work's title. You can provide the title in multiple languages.

Offers (required) contains the methods through which the customer can view the work: for free or through subscription. Offers can be limited by time or by region. The Offers element must contain at least one offer but can contain as many as necessary. There are four offer types:

The outline of an offer, including optional elements, can be represented as:

<_OfferType_> (such as <FreeOffer> or <SubscriptionOffer>)
    <Regions>
        <WindowStart>
            <WindowEnd>
                <LaunchDetails>
                    <Price> (rental or purchase only)
                        <Duration> (rental only)
</_OfferType_>

Regions (required) specifies the countries in which this offer is valid. Regions is required and must contain at least one Territories element.

WindowStart and WindowEnd (both optional) can be used together or separately to specify the time when this offer is valid. Before WindowStart and after WindowsEnd, the offer is not shown to the user.

LaunchDetails (optional) enables you to specify options for visual quality, audio language, and subtitles under this offer. It also allows you to define a special ID that can be used to directly launch a work with a predetermined configuration of those options.

If the availability of a given work changes, you must submit an updated catalog file with the new offer information.

The detail page for a movie, extra, or TV show displays all of the available offers and providers for that item. We display viewing options in this order (subject to change):

• Free offers
• Subscription content
• Fee-based content (purchase or rental)

Common Optional Elements for All Works

So far, we've discussed the common required elements and a handful of common optional elements. Using those alone, you have the knowledge to construct a valid catalog file.

However, those elements account for only about one-third of the total available to you. All the rest of the common elements are optional and are used to provide more information about the work.

For example, there are elements for genre, certification, cast and crew, plot description, studio, images, and customer rating. For a full list, see the Catalog Data Format (CDF) Schema.

A Note About Strings

Some string data in the CDF schema, such as a work's title and description, are defined as the custom LocalizedString type. Localized strings allow you to provide the same content in different languages, to be used according to the user's device language setting. These strings have the required attribute locale (of standard type xsd:language). Here is an example:

<Title locale="en-US">Edison Kinetoscopic Record of a Sneeze</Title>

Localized strings also have an optional attribute pronunciation (of standard type xsd:string). This attribute is provided for Japanese catalog entries that specify string text in kanji. The expected sort order in Japanese is based on pronunciation (which cannot be determined from kanji) rather than characters. The pronunciation attribute provides that information, typically using hiragana.

Elements Specific to the Work Type

In addition to the common elements, each work type has from one to five elements specific to that work type alone. In general, these elements have two uses: (1) to specify an original release or air date and (2) to tie works together, such as a TV episode to a TV show.

Release dates are optional but recommended, and are specified by either a ReleaseDate (for movies or TV shows) or OriginalAirDate (for TV episodes).

The elements that bundle shows, seasons, and episodes are required, and are discussed in more detail in the next section.

Refer to the Catalog Data Format (CDF) Schema for particulars on the type-specific elements.

Tying Shows, Seasons, and Episodes Together

TV episodes are aired during one season of a particular TV show. An extra can provide a preview or behind-the-scenes information about a movie.

The CDF provides elements that enable you to make those connections. When a Fire TV user browses to a TV show and sees the show organized by seasons with each episode shown sequentially in its season, that is the result of these elements.

In general, you can associate one work with another by either ID or title. An ID must match the ID of another work in your catalog. If that work is not in your catalog, you can use a title instead. The title isn't required to match anything in your catalog and is only used to group works. 

The following table shows these elements for each work type:

Rather than a title, TvEpisode uses a number to specify a season not in your catalog and Extra uses a link to an external ID scheme, such as IMDb. Also, while you can choose which to use, one in each element link pair is required for TvEpisode and TvSeason. The link value is optional for Extra, which can be standalone works.

The following illustration shows how the various elements and values are matched for a TV show when using IDs.

For instance, if a TvShow had an ID of TV-123456, the ShowID values in TvEpisode and TvSeason would also equal TV-123456.

Requirements for Box Art Images (ImageUrl)

The ImageUrl element, one of the optional elements common to all works, provides the URL of an image that represents the work, sometimes called the "box art." If you don't include ImageUrl, we attempt to use art available from other sources such as IMDb, if we can make a match, or we might use a generic placeholder image.

Image requirements

At a minimum, we recommend that your images meet the specifications described. Note that this refers to the box art image, not the work itself.

CDF FAQ

Q: How do I create my catalog file?

A: You create this file programmatically by exporting your metadata to an XML file that fits the CDF format.

Q: I have a TV show with seasons and episodes. What content types should I use to categorize my show?

A: Use TvShow, TVSeason, and TvEpisode.

Q: I have a TV show with sequential episodes, but that don't have a sequence number. Instead of sequence number, these episodes are ordered by their air-date. Which content type should I use?

A: Use the TvShow type.

Q: I have a news-type content where the episodes do not have seasons but do have an air date. What content type should I use?

A: Use the TvShow type.

Q: I have a show with seasons, but I do not have the actual values for the seasons. What should I do?

A: You are required to include season values for a show with seasons, which prevents a bad user experience. To obtain season information, try looking at an authority catalog such as IMDb. Amazon usually recommends excluding season-based content that lacks season values, as opposed to trying to make the show fit into another content type. Omitting this content should help preserve a positive viewer experience for your users.

Q: These all seem like an awful lot of rules to remember. How can I tell what to do without having to memorize every little nuance?

A: Generally, go by what your customers would expect. For example, if you have a TV series that is a talk show that airs nightly, your customers probably will not tend to think of that series as having seasons. In this case, air date is more important. However, if you have a popular series that tends to be binge-watched by users, season and episode number will likely be much more important to that viewer base.

Q: Ok, I've created my catalog file. Now what? Can I just upload it to AWS S3?

A: Amazon strongly recommends validating the XML in your catalog file before uploading it to AWS S3. If your CDF contains any poorly formed or invalid XML, the file will be rejected by Amazon. See Step 2: Validate Your Catalog File for more details.

Next Steps

After you create your catalog file, move on to Step 2: Validate Your Catalog File.

Last updated: Dec 18, 2023