Amazon Developer

as

Settings
Sign out
Notifications
Alexa
Amazon Appstore
Ring
AWS
Documentation
Support
Contact Us
My Cases
Devices
Build
Test
Publish
Connect
Documentation
Skip to main content
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.
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.
Expected output (success):
Expected output (failure):

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.

Upload workflow

To upload your catalog files
  1. Assume the IAM role.
    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.
  4. Upload the manifest file.
    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.

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.
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.
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.
You can also access the report by browsing the reports directory with the following commands.
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.
Last modified on May 27, 2026