Step 2: Upload Your Catalog to Staging

This guide covers creating, validating, and uploading your catalog to the staging environment.

1. Create your catalog

Each file in your catalog submission must conform to the Enhanced Metadata Bridge for Entertainment Resources (EMBER) schema. You can submit a full catalog that includes all your video metadata or an incremental catalog that includes only changes.

Catalog upload types

Quick start template

The following is a minimal valid EMBER catalog for a single movie with an offer.

<?xml version="1.0" encoding="UTF-8"?>
<DataCollections schemaVersion="1.0.0">
    <!-- Define your programs -->
    <ProgramCatalog id="MY_CATALOG" version="1">
        <Movie id="MOVIE_001" version="1">
            <ExternalIds>
                <ExternalId scheme="imdb">tt1234567</ExternalId>
            </ExternalIds>
            <Titles>
                <Title language="en" default="true">Example Movie</Title>
            </Titles>
            <Descriptions>
                <Description language="en" default="true">
                    A thrilling adventure film about discovery and courage.
                </Description>
            </Descriptions>
            <ReleaseDates>
                <ReleaseDate releaseType="streaming">2024-01-15</ReleaseDate>
            </ReleaseDates>
        </Movie>
    </ProgramCatalog>

    <!-- Define how customers access content -->
    <OfferCatalog id="MY_OFFERS" version="1">
        <ProgramOffers id="OFFER_001" version="1" programRef="MOVIE_001">
            <ProgramOffer>
                <Entitlements>
                    <Entitlement type="free"/>
                </Entitlements>
            </ProgramOffer>
        </ProgramOffers>
    </OfferCatalog>
</DataCollections>

For complete schema documentation, see EMBER Specification Overview.

Catalog creation requirements

Before creating your catalog, review the core concepts in the EMBER Specification Overview, particularly the sections on identifiers, versioning, element ordering, localization, and relationships. These rules govern how your catalog is structured and processed.

Key points to keep in mind:

• IDs must be durable (never change after creation), unique, and case-sensitive. For details, see Identifiers.
• The system always applies the highest version number. The system ignores lower version numbers even if received later. For details, see Versioning.
• Element ordering is strict. EMBER uses xs:sequence, so child elements must appear in XSD-defined order. Incorrect ordering causes validation failure. For details, see Element order dependency.
• Localization requires exactly one default="true" entry per localizable element, by using BCP-47 language codes and ISO 3166-1 territory codes. For details, see Localization.
• Relationships connect TV hierarchies (series to season to episode) and link extras to main content. TVSeason must include isSeasonOfSeries. TVEpisode must include isEpisodeOfSeason or isEpisodeOfSeries. For details, see Relationships.

Follow these guidelines for file size and compression:

• Use file compression for efficiency. Compress each data file individually by using GZip (.gz) or Zstandard (.zst) formats.
• Maximum size per compressed file: 100 MB
• Maximum total submission size (compressed): 10 GB
• If your catalog exceeds 100 MB compressed, split it into multiple files (for example, by catalog type or content type).

2. Validate your catalog

After creating your catalog file, validate it locally before uploading. The catalog ingestion service rejects files that aren't well-formed XML or that fail schema validation.

Download the EMBER XSD schema

Download the EMBER schema file: EMBER XSD file. Save it in the same directory as your catalog file.

Validate with xmllint

Mac and Linux include xmllint by default. Run the following command.

xmllint --noout --schema EMBER_{version}.xsd your-catalog.xml

Expected output (success):

your-catalog.xml validates

Expected output (failure):

your-catalog.xml:42: element Movie: Schemas validity error:
Element 'Movie': Missing child element(s). Expected is ( Titles ).
your-catalog.xml fails to validate

Validate with an IDE

Most IDEs have built-in XML validation:

• Visual Studio Code: Install the XML extension by Red Hat. Errors appear as you type.
• IntelliJ IDEA: Right-click your XML file, then choose Validate. Or configure under Settings > Languages & Frameworks > Schemas and DTDs.
• Eclipse: Right-click your XML file, then choose Validate.

Common validation errors

What XML validation catches and what it doesn't

Local validation (xmllint or IDE) catches:

• Malformed XML (broken tags, unclosed elements)
• Elements and attributes not defined in the schema
• Required elements that are missing
• Incorrect element ordering
• Invalid data types and formats

Local validation doesn't catch (caught at ingestion):

• Referential integrity. For example, a TVEpisode referencing a TVSeason that doesn't exist in the catalog.
• Business rules. For example, a TVEpisode missing a required series relationship (isEpisodeOfSeries).
• Image accessibility. For example, image URLs that aren't publicly reachable.
• Duplicate IDs. For example, two entities with the same ID in the same catalog.
• Cross-catalog reference resolution. For example, ProgramOffers referencing a program that doesn't exist.

3. Upload your catalog

After validating your catalog, upload it to the Amazon S3 bucket that Amazon configured for you.

S3 folder structure

Your S3 bucket has the following folder structure.

s3://amazon-media-catalogs/<your-provider-prefix>/
├── prod/                          ← Production environment
│   ├── catalogs/                  ← Upload production catalog files here
│   ├── manifests/                 ← Upload production manifest files here
│   └── reports/                   ← Production ingestion reports appear here
└── staging/                       ← Staging environment
    ├── catalogs/                  ← Upload staging catalog files here
    ├── manifests/                 ← Upload staging manifest files here
    └── reports/                   ← Staging ingestion reports appear here

Upload workflow

To upload your catalog files

1. Assume the IAM role.

    aws sts assume-role \
    --role-arn <role-arn-from-your-rep> \
    --role-session-name catalog-upload
   

   For more details, see Assume the IAM role for catalog upload.

2. Export the returned credentials as environment variables as explained in Assume the IAM role for catalog upload.
3. Upload the catalog files.

    aws s3 cp my-catalog.xml.zst \
    s3://amazon-media-catalogs/<provider>/staging/catalogs/catalog-20250420-120000.xml.zst
   

4. Upload the manifest file.

    aws s3 cp my-manifest.manifest \
    s3://amazon-media-catalogs/<provider>/staging/manifests/manifest-20250420-120000.manifest
   

   This action starts the ingestion process. For details about the manifest file, see Upload the manifest to start ingestion.

4. Upload the manifest to start ingestion

Uploading the manifest file starts the ingestion process. Make sure to upload the manifest only after you've uploaded your catalog files. Use the following command to upload the manifest file.

aws s3 cp my-manifest.manifest \
s3://amazon-media-catalogs/<provider>/staging/manifests/manifest-20250420-120000.manifest

Manifest file

The manifest file tells the ingestion service which catalog files to process. Uploading a manifest starts ingestion immediately.

Manifest requirements

The manifest file must meet the following requirements:

• Filename – Must end with .manifest (for example, catalog_upload_20250420.manifest)
• Format – JSON
• File names must be unique – Manifest and catalog file names can't overwrite existing files. Use timestamps or UUIDs to ensure uniqueness.

Manifest format

The following example shows the structure of a basic manifest file with a single catalog.

{
    "s3Bucket": "amazon-media-catalogs",
    "s3Keys": [
        "<provider>/staging/catalogs/catalog-20250420-120000.xml.zst"
    ],
    "type": "CATALOG_FULL",
    "schema": "EMBER"
}

Manifest fields

The following table describes each field in the manifest file.

Multi-file manifest example

You can include multiple catalog files in a single manifest. The following example references three separate files for programs, offers, and schedules.

{
    "s3Bucket": "amazon-media-catalogs",
    "s3Keys": [
        "<provider>/staging/catalogs/programs-20250420.xml.zst",
        "<provider>/staging/catalogs/offers-20250420.xml.zst",
        "<provider>/staging/catalogs/schedules-20250420.xml.zst"
    ],
    "type": "CATALOG_FULL",
    "schema": "EMBER"
}

The system processes all files listed in s3Keys as a single atomic submission. If any file fails XML validation, the system rejects the entire submission.

Upload requirements

The following table summarizes the requirements for catalog uploads.

5. Review ingestion reports

After you upload your catalog, the ingestion system processes your data and generates reports hourly (when items have been processed in the preceding hour). Reports are HTML files placed in the reports/ directory of your S3 bucket.

Receive report notifications by email

Ask your Amazon representative to add you to the ingestion report email distribution list. The system sends separate emails for successes and failures. Request to be added to both lists.

The email provides:

• A summary of items processed in the preceding hour
• An AWS CLI command to download the full report

Download a report

When you receive an ingestion report email notification, the email contains the exact download command. Copy and paste it into your terminal.

aws s3api get-object --region us-east-1 \
  --bucket amazon-media-catalogs \
  --key <provider>/staging/reports/04_20_2025/report-1713622889665-20250420012129.html \
  report.html

You can also access the report by browsing the reports directory with the following commands.

# List available reports
aws s3 ls s3://amazon-media-catalogs/<provider>/staging/reports/

# Download a specific report
aws s3 cp \
  s3://amazon-media-catalogs/<provider>/staging/reports/04_20_2025/report-1713622889665.html \
  ./report.html

Open report.html in a web browser to view the full report.

Understand the report

The ingestion report has the following sections.

Summary

The summary shows the overall ingestion results which includes the following:

• Ingestion ID and timestamp
• Total items processed
• Counts (number of added, updated, deleted, unchanged, and skipped items)
• Error, warning, and suggestion message counts

Errors, warnings, and suggestions

In this part of the report, expand each section to see individual messages and the IDs of affected items.

• Errors (must fix) – The system skips items with errors and doesn't ingest them. You must fix these for content to appear.
• Warnings (should fix) – The system ingests the content but it might have reduced functionality. Fix these for an optimal experience.
• Suggestions (optional) – Optimization recommendations for better discovery and metadata quality.

Counts

The counts section provides a detailed breakdown of added, deleted, updated, unchanged, and skipped items. Choose the Details button to see the specific IDs in each category. Compare these against your expected changes as a final verification.

Catalog summary report

In addition to hourly ingestion reports, the system generates a catalog summary report daily. This report provides a consolidated view of your entire catalog status across all catalog submissions, including all outstanding errors, warnings, and suggestions regardless of when they were introduced. Use this report for ongoing catalog health monitoring.

You can find this report in the following location: s3://amazon-media-catalogs/<provider>/prod/reports/<Date>/catalog-summary-<DateTime>.html.

• Previous – Step 1: Set Up Your Account
• Next – Step 3: Test Your Catalog in Staging

Last updated: May 27, 2026