EMBER Specification Overview

The Enhanced Metadata Bridge for Entertainment Resources (EMBER) is Amazon's XML schema for describing entertainment content metadata. The schema provides a structured, extensible format for representing diverse content types and their associated metadata across streaming and broadcast television.

EMBER currently supports the following content types:

• Video-on-demand programming – movies, TV series, and documentaries
• Linear broadcast content – TV channels, Free Ad-Supported Television (FAST) channels, and 24-hour schedules
• Live event programming – sports events, concerts, and special performances

The schema replaces Amazon's legacy Catalog Data Format (CDF) with enhanced capabilities for modern streaming services, including improved localization support, comprehensive relationship modeling, and flexible policy management.

XSD schema architecture

Every EMBER document contains one DataCollections root element that serves as the top-level container for all catalog types.

<?xml version="1.0" encoding="UTF-8"?>
<DataCollections schemaVersion="1.0.0">
    <!-- One or more catalog elements -->
</DataCollections>

The optional schemaVersion attribute identifies the EMBER schema version. The default value is 1.0.0. This attribute enables version-aware processing, which supports future schema evolution.

Catalog types

EMBER organizes metadata into six specialized catalog types, each addressing a specific aspect of the content delivery chain. The following table describes each catalog type and its key elements. For examples of each catalog type, see EMBER Examples.

Core concepts

This section covers the foundational concepts that apply across all EMBER catalog types.

Element order dependency

The EMBER schema uses xs:sequence within each program type and entity. Child elements at those levels must appear in the exact order defined in the XSD schema. Incorrect element ordering causes XML validation failure, even if all required elements are present. For example, elements within Movie and within nested containers such as Credits, must follow XSD-defined order.

However, the root DataCollections element and the catalog containers (ProgramCatalog, ScheduleCatalog, OfferCatalog, StationCatalog, LineupCatalog, PolicyCatalog) use xs:choice, so their child elements can appear in any order. For example, within a ProgramCatalog, program types such as Movie, TVEpisode, and TVSeries can appear in any order.

Valid movie example – Correct order

The following example shows the correct element order for a Movie element.

<Movie id="MOVIE_123" version="1">
    <!-- Must appear in this exact order per XSD: -->
    <ExternalIds>...</ExternalIds>
    <Titles>...</Titles>
    <Descriptions>...</Descriptions>
    <Synopses>...</Synopses>
    <Images>...</Images>
    <Genres>...</Genres>
    <Keywords>...</Keywords>
    <Ratings>...</Ratings>
    <Studios>...</Studios>
    <Credits>...</Credits>
    <Tags>...</Tags>
    <RunLengths>...</RunLengths>
    <PictureColor>...</PictureColor>
    <ReleaseDates>...</ReleaseDates>
    <Relationships>...</Relationships>
</Movie>

Invalid movie example – Incorrect order

The following example shows what happens when elements appear out of order. The Genres element is placed before Images, which causes a validation error.

<Movie id="MOVIE_123" version="1">
    <Titles>...</Titles>
    <Genres>...</Genres>         <!-- Wrong position -->
    <Images>...</Images>         <!-- Should come before Genres -->
    <!-- XSD Validation Error: Element 'Genres' unexpected,
         expected 'Descriptions', 'Synopses', or 'Images' -->
</Movie>

Optional elements can be omitted, but any elements you include must appear in their correct sequence position.

Cross-catalog references

EMBER catalogs reference each other through a structured reference system that maintains referential integrity and enables flexible organization. The reference system links entities across catalogs without data duplication. There are two types of references: entity references and catalog references.

Entity references are attributes that link to specific entities by their ID. The following table describes these attributes.

Catalog references are attributes that specify which catalog contains the referenced entity. If omitted, each attribute uses a default value:

• programCatalogRef – Specifies which ProgramCatalog contains the program. Default: DEFAULT_PROGRAM_CATALOG.
• stationCatalogRef – Specifies which StationCatalog contains the station. Default: DEFAULT_STATION_CATALOG.
• policyCatalogRef – Specifies which PolicyCatalog contains the policy. Default: DEFAULT_POLICY_CATALOG.
• scheduleCatalogRef – Specifies which ScheduleCatalog contains schedules. Default: DEFAULT_SCHEDULE_CATALOG.

The following examples show how a ProgramOffer catalog can reference a movie from a program catalog.

<!-- Simple reference using default catalog -->
<ProgramOffers id="OFFER_MOVIE_123" version="1" programRef="MOVIE_123">
    <!-- Resolves to Movie with id="MOVIE_123" in DEFAULT_PROGRAM_CATALOG -->
</ProgramOffers>

<!-- Explicit catalog reference -->
<ProgramOffers id="OFFER_MOVIE_123" version="1" programRef="MOVIE_123" programCatalogRef="VOD_CATALOG">
    <!-- Resolves to Movie with id="MOVIE_123" in catalog "VOD_CATALOG" -->
</ProgramOffers>

Parent elements can set default catalog references that children inherit and can override.

<Schedule programCatalogRef="LOCAL_PROGRAMS">
    <Airing programRef="PROG_1"/>  <!-- Uses LOCAL_PROGRAMS -->
    <Airing programRef="PROG_2"
            programCatalogRef="NETWORK_PROGRAMS"/>  <!-- Override -->
</Schedule>

EMBER maintains referential integrity by using following rules:

• All references must resolve to existing entities.
• The referenced ID must exist in the specified or default catalog, and the referenced entity must be the appropriate type, for example, a programRef must point to a program, not a station.
• Circular dependencies aren't allowed.

Identifiers

Every entity in EMBER has a unique id attribute that serves as its primary identifier. The id attribute must meet the following requirements:

• Durable – Don't change the ID after entity creation.
• Unique – The ID must be unique within your partner namespace and entity type.
• Case-sensitive – MOVIE_123 and movie_123 are different IDs.
• Format – Alphanumeric characters plus _, -, ., and : are valid.
• Minimum length – One character.

The following table shows recommended naming conventions.

This example shows how to apply this naming convention to a Movie element.

<Movie id="MOVIE_AVENGERS_2024" version="1">

External IDs

External identifiers link EMBER entities to external metadata systems, enabling content matching and cross-system tracking.

<ExternalIds>
    <ExternalId scheme="scheme_name">identifier_value</ExternalId>
</ExternalIds>

The following table lists supported external ID schemes.

As a best practice, include all available external IDs to improve content matching and deduplication accuracy.

Versioning

The version attribute provides optimistic concurrency control, ensuring consistency when updates arrive out of order. The version value is an integer—either sequential or timestamp-based—where a higher number takes precedence. The system ignores lower versions, even if they arrive later. The default value is 1 if omitted.

<!-- Initial creation -->
<Movie id="MOVIE_123" version="1">...</Movie>

<!-- Update with higher version -->
<Movie id="MOVIE_123" version="2">...</Movie>

<!-- Later update -->
<Movie id="MOVIE_123" version="5">...</Movie>

<!-- Out-of-order update ignored (version too low) -->
<Movie id="MOVIE_123" version="3">...</Movie>  <!-- Ignored, current is 5 -->

Common version strategies include:

• Sequential – Increment by one for each update: 1, 2, 3, and so on.
• Timestamp – Use Unix epoch seconds: 1713622889, 1713622890, and so on.
• Hybrid – Combine date and sequence: 20250420001, 20250420002, and so on.

Localization

EMBER provides multi-language, multi-territory support through three coordinated attributes:

• language – A BCP-47 language code, such as en, es, es-MX, pt-BR, or fr-CA.
• territories – ISO 3166-1 alpha-2 country codes, comma-separated or GLOBAL. For example, US, US,CA,MX, or GLOBAL.
• default – A boolean flag (true or false) that marks the fallback value.

EMBER uses fallback resolution logic to display the most appropriate localized content. When a customer requests content, the system searches in this order:

1. Exact match – Both language and territories match.
2. Language match – Language matches, territories ignored.
3. Default fallback – Uses the entry with default="true".

<Titles>
    <Title language="en" default="true">The Avengers</Title>
    <Title language="en" territories="GB">Marvel Avengers Assemble</Title>
    <Title language="es">Los Vengadores</Title>
</Titles>

In this example:

• A UK customer (en-GB) sees "Marvel Avengers Assemble" through exact match.
• A US customer (en-US) sees "The Avengers" through language match to default.
• A Spanish customer (es-MX) sees "Los Vengadores" through language match.
• A German customer (de-DE) sees "The Avengers" through default fallback.

Localization rules:

• One entry must have default="true" per property.
• The default should be the original or primary language.
• Use simple language codes such as en and es unless dialect differentiation is needed.
• Use territories="GLOBAL" or omit the attribute for worldwide content.

The following is a list of common country codes:

• US (United States)
• CA (Canada)
• MX (Mexico)
• GB (United Kingdom)
• DE (Germany)
• FR (France)
• ES (Spain)
• IT (Italy)
• JP (Japan)
• AU (Australia)
• BR (Brazil)
• IN (India)

For more country codes, visit ISO 3166-1 alpha-2.

Relationships

EMBER models content hierarchies and associations through structured Relationship elements within programs.

Television content follows a three-level hierarchy connected by relationship elements.

TVSeries
└─ isSeasonOfSeries (seasonNum) → TVSeason
   └─ isEpisodeOfSeason (episodeNum) → TVEpisode

In this hierarchy:

• TVSeries links to TVSeason by isSeasonOfSeries using the seasonNum attribute.
• TVSeason links to TVEpisode by isEpisodeOfSeason using the episodeNum attribute.

The following table describes the available relationship types.

Required relationships:

• TVSeason – Must include isSeasonOfSeries.
• TVEpisode – For regular TV series episodes, include isEpisodeOfSeason and isEpisodeOfSeries. For mini series episodes, include isEpisodeOfSeries.
• Extra – Should include isExtraOf (recommended but not required).

Create entities in this order:

1. TVSeries
2. TVSeason
3. TVEpisode

TV episode relationship example

This example shows a TVEpisode that links to both its parent season and parent series using isEpisodeOfSeason and isEpisodeOfSeries.

<TVEpisode id="FRIENDS_S01E01" version="1">
    <Titles>
        <Title language="en" default="true">The One Where Monica Gets a Roommate</Title>
    </Titles>
    <Relationships>
        <isEpisodeOfSeason programRef="FRIENDS_S01"
                episodeNum="1" premiere="true"/>
        <isEpisodeOfSeries programRef="FRIENDS" episodeNum="1"/>
    </Relationships>
</TVEpisode>

Extra relationship example

Extras link to main content by using isExtraOf.

<Extra id="AVENGERS_TRAILER" version="1" category="trailer">
    <Titles>
        <Title language="en" default="true">The Avengers - Official Trailer</Title>
    </Titles>
    <Relationships>
        <isExtraOf programRef="MOVIE_AVENGERS_2024" orderNum="1"/>
    </Relationships>
</Extra>

General relationship example

Use isRelatedTo to create non-hierarchical connections between content.

<Movie id="HOBBIT_1" version="1">
    <Titles>
        <Title language="en" default="true">The Hobbit: An Unexpected Journey</Title>
    </Titles>
    <Relationships>
        <isRelatedTo programRef="LOTR_1"/>
        <isRelatedTo programRef="LOTR_2"/>
        <isRelatedTo programRef="LOTR_3"/>
    </Relationships>
</Movie>

Source attributes

Source attributes provide provenance tracking for editorial content, documenting where metadata originated. The attribute group includes:

• sourceName – Name of the metadata provider, such as "IMDb", "Gracenote", or "Rotten Tomatoes."
• sourceDate – Date the metadata was retrieved, in YYYY-MM-DD format.
• sourceId – The provider's identifier for the data record.

All three attributes are optional, enabling flexible attribution based on available information. You can attach source attributes to any editorial element, including titles, descriptions, images, genres, ratings, and credits.

<Title language="en"
       default="true"
       sourceName="IMDb"
       sourceDate="2024-03-15"
       sourceId="tt0076759">Star Wars</Title>

<CustomerRating score="8.6"
                maxScore="10"
                numVotes="1500000"
                sourceName="IMDb"
                sourceDate="2024-03-15"/>

Delete and catalog actions

The Delete element removes entities from catalogs by using ID and version matching. A delete succeeds if the specified version is greater than or equal to the current entity version. The system ignores a delete if the specified version is lower than the current entity version. This protects against out-of-order message delivery.

<ProgramCatalog id="MY_CATALOG" version="1">
    <!-- Remove expired movie -->
    <Delete id="OLD_MOVIE" version="100"/>

    <!-- Remove multiple entities -->
    <Delete id="EXPIRED_SERIES" version="50"/>
    <Delete id="EXPIRED_SEASON" version="25"/>
</ProgramCatalog>

When deleting hierarchical content, delete children before parents, as shown in this example.

<!-- Correct order -->
<Delete id="SERIES_S01E01" version="10"/>  <!-- Episode first -->
<Delete id="SERIES_S01" version="5"/>      <!-- Season second -->
<Delete id="SERIES_1" version="3"/>        <!-- Series last -->

The catalog action attribute controls catalog-level update behavior. The following table describes the available values.

The following example uses action="upsert" to add a new movie, update an existing movie, and delete an expired movie without affecting the rest of the catalog.

<!-- Incremental update -->
<ProgramCatalog id="MY_CATALOG" version="1" action="upsert">
    <Movie id="NEW_MOVIE" version="1"><!-- ... --></Movie>  <!-- Added -->
    <Movie id="EXISTING" version="2"><!-- ... --></Movie>   <!-- Updated -->
    <Delete id="OLD_MOVIE" version="5"/>                    <!-- Removed -->
    <!-- All other existing movies unchanged -->
</ProgramCatalog>

This example uses action="replace" to rebuild the entire catalog, which removes any movies not included in the submission.

<!-- Complete replacement -->
<ProgramCatalog id="MY_CATALOG" version="1" action="replace">
    <Movie id="MOVIE_1"><!-- ... --></Movie>
    <Movie id="MOVIE_2"><!-- ... --></Movie>
    <!-- Only these movies exist after ingestion -->
</ProgramCatalog>

Use action="upsert" for regular updates. Reserve action="replace" for complete catalog rebuilds and full refreshes.

Data type reference

The EMBER schema uses both built-in XML data types and custom EMBER-specific data types. The following tables describe each type.

Built-in XML data types

EMBER-specific data types

Related topics

• All EMBER Elements
• Catalog Integration Overview

Last updated: May 27, 2026