EMBER Best Practices

This page covers recommended practices for catalog integration, from initial planning through ongoing maintenance. Following these guidelines helps you avoid common issues, improve content matching, and maintain a healthy catalog.

Planning and setup

This section covers the initial steps for a successful catalog integration.

Understand your integration timeline

Catalog integration requires careful planning. Allocate two to four weeks for initial setup:

• Week 1 – AWS account setup, S3 bucket provisioning, and IAM role configuration.
• Week 2 – Test catalog creation, validation, and initial submission to the staging environment.
• Weeks 3–4 – Error resolution, production launch, and monitoring.

Assign dedicated resources

Catalog integration involves metadata transformation, automation scripting, and ongoing monitoring. Make sure your team can cover the following areas:

• Export and transform content metadata into Enhanced Metadata Bridge for Entertainment Resources (EMBER) format.
• Script automation for catalog generation and upload.
• Validate catalogs, test on devices, and monitor ingestion reports.
• Configure AWS CLI, manage credentials, and set up cron jobs.

Start with the staging environment

Always validate in the staging environment before submitting to production and follow these high-level steps:

1. Submit test catalogs to the staging/ directory.
2. Add test devices to the allow list with your Amazon representative.
3. Verify that content appears correctly on devices.
4. Fix all errors and warnings before production launch.

Upload strategy

How you upload your catalog affects processing speed, risk, and reliability.

Use full catalog replace sparingly

To completely rebuild your catalog use type="CATALOG_FULL" in the manifest file. This approach can remove stale or unreferenced entities but carries higher risk because any missing content is deleted. Schedule full replacements during off-peak hours.

Use incremental updates for regular changes

For daily or weekly updates, use type="CATALOG_UPDATE" in the manifest file. Incremental updates include only changed entities (new, updated, or deleted), preserve unchanged content, process faster, and carry lower risk.

Understand catalog-level actions

In addition to the manifest-level type (CATALOG_FULL and CATALOG_UPDATE), each catalog element has an action attribute that controls how its contents are processed:

• upsert (default) – Adds new entities, updates existing entities, and preserves everything else. Use this for incremental updates.
• replace – Removes all existing entities in the catalog and replaces them with the contents of the submission. Use this with caution, as any entity not included in the file is deleted.

To remove individual entities without replacing the entire catalog, use the Delete element within an upsert update. When deleting hierarchical content, delete children before parents (episodes before seasons, seasons before series).

For the full reference, including delete versioning behavior and examples, see Delete and catalog actions.

Automate your upload process

Manual uploads are error-prone. Create automated scripts that perform the following steps:

1. Generate the catalog from your content management system (CMS) database.
2. Validate against the XSD automatically.
3. Compress files.
4. Assume the IAM role and refresh credentials.
5. Upload with proper sequencing.
6. Schedule through a cron job (daily at 2:00 AM recommended).

Roll back to a known good catalog

If a catalog submission introduces errors, such as missing content, broken relationships, or incorrect metadata, you can revert to a previous known good state by submitting a full replacement with your last validated catalog.

To roll back your catalog:

1. Identify the last validated catalog version in your archive.
2. Update the manifest file to use type="CATALOG_FULL" with a new, higher version number.
3. Submit the archived catalog files to the S3 path.
4. Monitor the ingestion report to confirm the rollback processed without errors.

To make rollbacks reliable, follow these practices:

• Archive every successfully ingested catalog with its timestamp and version number.
• Store archives in a consistent location.
• Validate archived catalogs against the XSD before resubmitting.
• Keep at least three recent good catalogs available for recovery.

Monitoring and maintenance

Regular monitoring helps you catch issues early and keep your catalog healthy.

Monitor ingestion reports daily

Subscribe to ingestion report emails and do the following:

• Verify the error count equals zero.
• Review warnings and plan fixes.
• Verify item counts match expectations.
• Track skipped items.

Review catalog summary reports weekly

The daily catalog summary report provides a holistic view of your catalog health. Review the following:

• All current errors and warnings
• Optimization suggestions
• Content quality metrics
• Week-over-week trends

Maintain upload frequency requirements

Required minimums:

• Incremental updates: At least every seven days, or content might be deprioritized.
• Full catalog refresh: At least every 30 days, or the catalog might be suppressed.

Recommended cadence:

• Daily: New releases, availability changes, schedule updates
• Weekly: Metadata corrections, image updates
• Monthly: Full validation and cleanup

File organization

Organizing your catalog files consistently makes submissions easier to manage and debug.

Split large catalogs into multiple files

Don't create monolithic XML files. Instead, split catalogs by type or update frequency:

• By catalog type: movies.xml, tv-shows.xml, schedules.xml
• By update frequency: daily-updates.xml, stable-content.xml

Keep each compressed file under 100 MB and the total submission under 10 GB compressed.

Use consistent file naming

Include timestamps in file names for tracking. For example:

• catalog-movies-20260425-140000.xml.zst
• catalog-schedules-20260425-140000.xml.zst
• manifest-20260425-140000.manifest

Consistent naming prevents accidental overwrites, provides clear submission history, and enables rollback if needed.

Organize multiple catalogs logically

When you use multiple catalogs of the same type, organize by purpose:

• ORIGINAL_CONTENT – Your original productions.
• LICENSED_CONTENT – Third-party licensed content.
• LOCAL_STATIONS – Local broadcast affiliates.
• EXTERNAL_STATIONS – TMS or Gracenote Video Data (GVD) referenced stations.

ID management

Consistent, durable IDs are critical for content tracking and cross-catalog references.

Use durable, meaningful IDs

IDs must never change after creation. Choose descriptive, permanent identifiers.

Good examples:

• id="MOVIE_AVENGERS_2024"
• id="SERIES_FRIENDS"
• id="NFL_2025_W01_SEA_SF"

Bad examples:

• id="Movie 123" (contains spaces)
• id="temp_id" (not durable)
• id="12345" (not descriptive)

Establish ID conventions

Document your ID patterns before you start building catalogs. Amazon recommends the patterns listed in the following table.

Never reuse IDs

When content is removed, retire its ID permanently. Don't reuse an ID for different content. Create new IDs for remakes or reboots, and maintain an ID registry or database.

Version management

Versioning controls how the system handles incremental catalog updates and prevents out-of-order overwrites.

Choose a versioning strategy

The following are three common versioning approaches.

Sequential (simple)

<Movie id="MOVIE_123" version="1">   <!-- Initial -->
<Movie id="MOVIE_123" version="2">   <!-- First update -->
<Movie id="MOVIE_123" version="3">   <!-- Second update -->

Timestamp (automatic)

<Movie id="MOVIE_123" version="1713622889">   <!-- Unix epoch -->
<Movie id="MOVIE_123" version="1713622950">   <!-- 61 seconds later -->

Hybrid (readable and automatic)

<Movie id="MOVIE_123" version="20260425001">   <!-- Date + sequence -->
<Movie id="MOVIE_123" version="20260425002">

Track versions in your system

Maintain version history for each entity:

• Store the current version for each entity in your database.
• Increment the version before each update.
• Never submit a version less than or equal to the current version.

Content metadata

This section covers recommended practices for the metadata fields that have the greatest impact on content matching and the customer experience.

Titles and descriptions

Provide territory-specific title variations when content has different titles in different regions.

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

Write engaging descriptions and synopses:

• Descriptions (50–200 characters): Concise, enticing summary.
• Synopses (200–500 characters): Detailed plot without spoilers.
• Use proper grammar and spelling.
• Avoid marketing hyperbole.
• Don't spoil major plot twists.

Images

Use high-quality images that meet the following requirements:

• Minimum resolution: HD (1920x1080).
• Recommended: 4K (3840x2160) for future-proofing.
• Maximum file size: 10 MB.
• Professional quality with no watermarks or artifacts.

Follow the image category guidelines in EMBER Images.

Make sure that all image URLs are publicly accessible so that Amazon's ingestion system can retrieve them:

• Use public HTTPS URLs.
• Valid SSL certificates are required.
• No authentication or headers required.
• Test that URLs return HTTP 200.
• Images must be available 24/7.

External IDs

External IDs are the primary matching mechanism. Include all available external IDs.

<ExternalIds>
    <ExternalId scheme="imdb">tt0076759</ExternalId>
    <ExternalId scheme="tms">MV123456789012</ExternalId>
    <ExternalId scheme="eidr">10.5240/XXXX</ExternalId>
    <ExternalId scheme="asin">B09ABC123</ExternalId>
</ExternalIds>

Without external IDs, your content might:

• Appear as a duplicate instead of merging with existing entries.
• Have lower search ranking.
• Miss cross-service recommendations.

Make sure to use standard identifier schemes. For a full list of supported identifier schemes, see External IDs.

Genres and keywords

Use EMBER genre schemes when possible.

<Genres>
    <!-- Prefer ember_genre scheme -->
    <Genre scheme="ember_genre">ember_genre_action</Genre>
    <Genre scheme="ember_genre">ember_genre_thriller</Genre>

    <!-- Free-form as fallback -->
    <Genre language="en">action</Genre>
</Genres>

Limit genres to two to four per program. Too many genres dilute categorization. Use subgenres when available.

Include relevant keywords for franchise names, character names, actor names, alternative titles, and common search terms.

<Keywords>
    <Keyword language="en">avengers</Keyword>
    <Keyword language="en">marvel</Keyword>
    <Keyword language="en">superhero</Keyword>
    <Keyword language="en">iron man</Keyword>
</Keywords>

Don't add excessive or irrelevant keywords. Avoid generic terms like "movie," "video," or "watch." Don't repeat title words. Prioritize quality over quantity.

TV content hierarchy

TV content requires a specific creation order to maintain valid relationships between series, seasons, and episodes.

Create entities in the correct order

Always create TV content in this order: TVSeries, then TVSeason, then TVEpisode.

<!-- Step 1: Create series -->
<TVSeries id="SERIES_1" version="1">
    <Titles>...</Titles>
</TVSeries>

<!-- Step 2: Create season (references series) -->
<TVSeason id="SERIES_1_S01" version="1">
    <Titles>...</Titles>
    <Relationships>
        <isSeasonOfSeries programRef="SERIES_1" seasonNum="1"/>
    </Relationships>
</TVSeason>

<!-- Step 3: Create episode (references season and series) -->
<TVEpisode id="SERIES_1_S01E01" version="1">
    <Titles>...</Titles>
    <Relationships>
        <isEpisodeOfSeason programRef="SERIES_1_S01" episodeNum="1"/>
        <isEpisodeOfSeries programRef="SERIES_1" episodeNum="1"/>
    </Relationships>
</TVEpisode>

Include both episode relationships

For each TVEpisode, include both isEpisodeOfSeason and isEpisodeOfSeries. This provides flexible navigation and supports both series-level and season-level browsing.

Ratings and content appropriateness

Content ratings help customers make informed viewing decisions. Provide territory-specific ratings for each region where your content is available.

Provide territory-specific ratings

Include the appropriate rating system and certification for each territory.

<Ratings>
    <Rating system="MPAA" certification="PG-13" territories="US">
        <Descriptors>
            <Descriptor code="V">Violence and action sequences</Descriptor>
        </Descriptors>
    </Rating>
    <Rating system="BBFC" certification="12A" territories="GB"/>
    <Rating system="FSK" certification="FSK 12" territories="DE"/>
</Ratings>

Use descriptors for transparency

Help parents make informed decisions by including reason codes (V for violence, L for language, S for sexual content), clear descriptor text, and official rating board language.

Live events and scheduling

Live events can be represented in two ways depending on your distribution model.

Use ProgramAiringOffers for app-based live streaming

Use ProgramAiringOffers when the event streams live in your app only. In this model, users access the event through your app (not a broadcast channel), and the Airing element has no stationRef attribute.

Examples include an NFL game exclusive to your app, a concert livestream exclusive to your service, a pay-per-view boxing match, an esports tournament, or a theater performance on your streaming service.

Use ScheduleCatalog for linear broadcast

Use ScheduleCatalog when the event broadcasts on a TV station or channel. In this model, the event is available to anyone tuned to that station, the Airing element has a stationRef attribute, and the event appears in the 24-hour broadcast schedule.

Examples include an NFL game on CBS, the Olympics on NBC, or an awards show on ABC.

Use both when applicable

Many partners broadcast the same event on linear TV and in their streaming app. In this case:

• Create one SportsEvent program.
• Reference it in ScheduleCatalog for linear broadcast.
• Reference it in ProgramAiringOffers for app streaming.
• Each reference can have different entitlements, blackout rules, and quality levels.

Reuse live events for VOD replay

After a live event concludes, you can offer it on-demand using the same program entity. Submit both ProgramAiringOffers and ProgramOffers in the same catalog update to ensure a seamless transition from live to on-demand.

During the event (time-bound live streaming)

<ProgramAiringOffers id="AIRING_OFFER_CONCERT_2026" version="1" programRef="CONCERT_2026">
    <ProgramAiringOffer start="2026-06-15T20:00:00Z"
                        end="2026-06-15T23:00:00Z">
        <Airing id="AIRING_CONCERT_2026"
                startTime="2026-06-15T20:00:00Z"
                duration="PT3H"
                programRef="CONCERT_2026">
            <Live/>
            <New/>
        </Airing>
        <Entitlements>
            <Entitlement type="subscription"/>
        </Entitlements>
        <LaunchTargets>
            <LaunchTarget type="FIRETV">
                amzn://apps/watch?id=CONCERT_2026&live=true
            </LaunchTarget>
        </LaunchTargets>
    </ProgramAiringOffer>
</ProgramAiringOffers>

After the event (VOD replay available indefinitely)

<ProgramOffers id="OFFER_CONCERT_2026" version="1" programRef="CONCERT_2026">
    <ProgramOffer>
        <Entitlements>
            <Entitlement type="subscription"/>
        </Entitlements>
        <VideoResolutions>
            <VideoResolution>4K</VideoResolution>
        </VideoResolutions>
        <LaunchTargets>
            <LaunchTarget type="FIRETV">
                amzn://apps/watch?id=CONCERT_2026&replay=true
            </LaunchTarget>
        </LaunchTargets>
    </ProgramOffer>
</ProgramOffers>

VOD replay extends content value through catch-up viewing, rewind and pause capabilities, no time constraints, and the ability to monetize with different tiers.

Linear catalogs

If you distribute linear broadcast content (TV stations, Free Ad-Supported Television (FAST) channels), Amazon strongly recommends you use ExternalStation references with TMS or Gracenote station IDs.

Use fully-defined Station elements only when you have original content that is not available in external systems, such as local productions or custom FAST channels. When creating a fully-defined station using the Station element, you must include applicable schedules, programs, offers, and policies.

Benefits of using external station references:

• No program metadata required – the external system already has full program details.
• No schedule submission needed – TMS or Gracenote provides schedule data.
• Automatic updates – program and schedule changes are handled by the external provider.
• Reduced maintenance – you only maintain StationOffers (access and entitlements).
• Faster integration – submit station IDs and access rules, not thousands of programs.

What you provide:

• ExternalStation elements with TMS or GVD IDs.
• StationOffers (entitlements, geo-restrictions).

What the external provider handles:

• All program metadata (titles, descriptions, images).
• Complete broadcast schedules (24-hour daily updates).
• Program relationships and series hierarchies.
• Ratings and content advisories.

Related topics

• EMBER Catalog Integration Overview – Overview of the catalog integration process
• EMBER Specification Overview – Schema reference with catalog types, core concepts, and data types
• EMBER Examples – XML examples for common catalog scenarios
• All EMBER Elements – Complete element directory

Last updated: May 27, 2026