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.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.
TVSeasonmust includeisSeasonOfSeries.TVEpisodemust includeisEpisodeOfSeasonorisEpisodeOfSeries. For details, see Relationships.
- 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 includexmllint by default. Run the following command.
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
- Referential integrity. For example, a
TVEpisodereferencing aTVSeasonthat doesn’t exist in the catalog. - Business rules. For example, a
TVEpisodemissing 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,
ProgramOffersreferencing 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-
Assume the IAM role.
For more details, see Assume the IAM role for catalog upload.
- Export the returned credentials as environment variables as explained in Assume the IAM role for catalog upload.
-
Upload the catalog files.
-
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.
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.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 (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.
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.
