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
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.
Schema information
PropertyValue
XSD fileEMBER_1.0.0.xsd
Schema version1.0.0

XSD schema architecture

Every EMBER document contains one DataCollections root element that serves as the top-level container for all catalog types.
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.
CatalogContainsKey elementsDescription
ProgramCatalogMovie, TVEpisode, TVSeason, TVSeries, SportsEvent, Event, OffAir, Other, ToBeAnnounced, ExtraTitles, Descriptions, Synopses, Images, Genres, Keywords, Ratings, Studios, Credits, RunLengths, ReleaseDates, RelationshipsDefines content metadata.
For example, what programs exist and their descriptive attributes.
ScheduleCatalogScheduleAiring, AudioLanguages, SubtitleLanguages, GeoRestrictionsDefines broadcast timing.
For example, when programs air on specific stations.
OfferCatalogProgramOffers, ProgramAiringOffers, StationOffers, ProgramDiscoveryEntitlements, AudioLanguages, SubtitleLanguages, VideoResolutions, GeoRestrictions, LaunchTargets, Ranks, BadgesDefines access and discovery.
For example, how customers interact with content.
StationCatalogStation, ExternalStationTitles, Images, CallSign, OriginalBroadcastType, AffiliatedNetworks, VideoResolutions, AudioLanguagesDefines broadcast channels and networks.
For example, the distribution outlets for linear content.
LineupCatalogLineupChannels, StationTransport, GeoRestrictionsDefines channel organization.
For example, how stations are packaged for providers.
PolicyCatalogRegionPolicy, EntitlementPolicyRegion, PostalCode, EntitlementId, ShortDisplayNames, LongDisplayNamesDefines reusable rules.
For example, geographic restrictions and entitlement tiers.

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.
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.
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.
Attribute nameDescriptionUsed in
programRefReferences a program by ID. Points to Movie, TVSeries, TVSeason, TVEpisode, SportsEvent, Event, Extra, or Other.ProgramOffers, ProgramAiringOffers, ProgramDiscovery, Airing, Relationships
stationRefReferences a station by ID. Points to Station or ExternalStation.StationOffers, Schedule, Channel
policyRefReferences a policy by ID. Points to RegionPolicy or EntitlementPolicy.GeoRestriction, Entitlement
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.
Parent elements can set default catalog references that children inherit and can override.
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.
Entity typePatternExample
MovieMOVIE_TITLE_YEARMOVIE_AVENGERS_2024
TV seriesSERIES_TITLESERIES_FRIENDS
TV seasonSERIES_S##SERIES_FRIENDS_S01
TV episodeSERIES_S##E##SERIES_FRIENDS_S01E01
Sports eventLEAGUE_SEASON_DETAILSNFL_2025_W01_SEA_SF
StationCALLSIGN_NETWORK_CITYKIRO_CBS_SEATTLE
This example shows how to apply this naming convention to a Movie element.

External IDs

External identifiers link EMBER entities to external metadata systems, enabling content matching and cross-system tracking.
The following table lists supported external ID schemes.
SchemeSystemUsed forExample
imdbInternet Movie DatabaseMovies, TV, peoplett0076759, nm0000123
tmsTribune Media ServicesMovies, TV, stationsMV123456789012, TMS87654321
gvdGracenote Video DataMovies, TV, stationsGVD_HBO_EAST, GVD_12345
isanInternational Standard Audiovisual NumberMovies, TV0000-0000-0000-0000-0-0000-0000-0
eidrEntertainment Identifier RegistryMovies, TV10.5240/XXXX-XXXX-XXXX-XXXX-XXXX-X
asinAmazon Standard Identification NumberAmazon contentB09ABCD123
eanEuropean Article NumberPhysical media5051890000000
upcUniversal Product CodePhysical media012345678905
sportsradarSports RadarSports events, teams, playerssr:match:12345678
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.
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".
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.
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.
RelationshipFromToRequired attributesPurpose
isSeasonOfSeriesTVSeasonTVSeriesseasonNumLinks season to parent series
isEpisodeOfSeasonTVEpisodeTVSeasonepisodeNumLinks episode to parent season
isEpisodeOfSeriesTVEpisodeTVSeriesepisodeNumLinks episode to parent series. Mini series uses isEpisodeOfSeries without isEpisodeOfSeason.
isExtraOfExtraAny programorderNum (optional)Links bonus content to main content
isRelatedToAny programAny programNoneGeneral content relationship
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.
Extra relationship example Extras link to main content by using isExtraOf.
General relationship example Use isRelatedTo to create non-hierarchical connections between content.

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.

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.
When deleting hierarchical content, delete children before parents, as shown in this example.
The catalog action attribute controls catalog-level update behavior. The following table describes the available values.
ActionBehaviorUse case
upsert (default)Adds new entities, updates existing entities, and preserves others.Incremental updates. This is the most common action.
replaceRemoves all existing entities and adds new ones.Complete catalog rebuild. Use with caution.
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.
This example uses action="replace" to rebuild the entire catalog, which removes any movies not included in the submission.
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

Data typeFormat or rangeDescription
booleantrue, falseBoolean values. Used for flags such as default, adultProduct, notRated, closed, homeTeam, premiere, and finale.
decimalAny decimal numberNumbers with fractional components, such as 5.2, 8.99, or 100.0. Used for prices and rating scores. Example: score="4.8" maxScore="5".
int-2147483648 through 2147483647Standard integers. Used for counts and year values in copyright.
long-9223372036854775808 through 9223372036854775807Large integers. Used for version numbers and timestamps. Examples: version="1", version="1713622889".
nonNegativeInteger0, 1, 2, 3, …Zero or positive integers. Used for seasonNum, episodeNum, and orderNum. Examples: seasonNum="1", episodeNum="5".
positiveInteger1,2, 3, …Positive integers with a minimum of 1. Used when zero isn’t valid.
stringAny textGeneral text content. Used for names, descriptions, and URLs. Supports Unicode for international characters.
unsignedInt0 through 4294967295Non-negative integers with large range. Used for numVotes in customer ratings.

EMBER-specific data types

Data typeFormat or valuesDescription
AspectRatioType16:9, 4:3, 3:4, 2:3, 1:1, otherImage aspect ratios:
  • 16:9 – Widescreen
  • 4:3 – Standard TV
  • 3:4 – Portrait
  • 2:3 – Poster
  • 1:1 – Square
  • other – Other aspect ratio
CatalogActionTypeupsert, replaceCatalog update behavior:
  • upsert – Incremental (default)
  • replace – Complete rebuild
DateTimeTypeYYYY-MM-DDTHH:MM:SS±HH:MMISO-8601 date-time with time zone. Time zone is required as Z or ±offset.
Examples: 2025-04-20T15:30:00Z (Coordinated Universal Time), 2025-04-20T08:30:00-07:00 (PST).
DateTypeYYYY-MM-DDISO-8601 date format. Used for schedule dates and release dates.
Examples: 2025-04-20, 2025-12-31.
DurationTypeP[n]Y[n]M[n]DT[n]H[n]M[n]SISO-8601 duration.
  • P – Period prefix (required)
  • T – Time separator
Use T for time components.
Examples: PT30M (30 minutes), PT2H (2 hours), PT1H30M (1 hour 30 minutes).
EditTypeListORIGINAL, DIRECTORSCUT, EXTENDED, UNRATED, CENSORED, REGIONALIZED, COLORIZED, SHORTENEDA comma-separated list that indicates the edit version of the program. Valid edit types:
  • ORIGINAL – Default version if no special edit
  • DIRECTORSCUT – Director’s preferred version
  • EXTENDED – Extended with additional scenes
  • UNRATED – Without rating board cuts
  • CENSORED – Content cleaned for family viewing
  • REGIONALIZED – Country or region specific edit
  • COLORIZED – Color version produced from black and white version
  • SHORTENED – Materials removed for other than censorship reasons
Example: edit="DIRECTORSCUT,UNRATED"
EntitlementTypeEnumTypefree, subscriptionEntitlement types:
  • free – Content is available for free.
  • subscription – Content requires a subscription or an add-on subscription. For example, premium tier content or a sports add-on.
Use policyRef for complex tiers.
ExtraCategoryTypetrailer, teaser, clip, featurette, behindthescenes, deletedscenes, bloopers, commentary, interview, highlights, preevent, posteventEnumeration that represents the category of extra content. The extra content must relate to the original content, such as the movie or TV series available in the catalog. Valid values:
  • teaser – Brief preview offering hints without revealing plot details
  • trailer – Comprehensive preview showcasing story, characters, and themes
  • clip – Short excerpt demonstrating specific scenes or moments
  • featurette – Supplementary content about the production process, including making-of material
  • behindthescenes – Raw footage showing production process and on-set activities
  • deletedscenes – Content removed from the final release
  • bloopers – Outtakes and on-set mistakes
  • commentary – Additional audio or video featuring creator insights
  • interview – Conversations with cast, crew, or post-game interviews
  • highlights – Key moments or best parts compilation
  • preevent – Content leading up to the main event
  • postevent – Follow-up content after the main event
IDAlphanumeric plus the characters: _ - . :Partner identifiers. Minimum length one character. Case-sensitive.
Example: id="MOVIE_AVENGERS_2024".
ImageCategorybackground, cover, poster, episodic, title, logoImage types:
  • background – No text
  • cover – Burned-in title
  • poster – Vertical art
  • episodic – Still frame
  • title – Title treatment
  • logo – Station logo
ImageColorTypecolor, white, light, black, gray, darkLogo color variants for different UI backgrounds.
LanguageTypeBCP-47 codesLanguage tags.
Examples: en (English), es (Spanish), es-MX (Mexican Spanish), pt-BR (Brazilian Portuguese), fr-CA (Canadian French), zh-Hans (Simplified Chinese).
LaunchTargetTypeEnumWEB, FIRETVLaunch target types for launch URLs:
  • WEB – Web browser
  • FIRETV – Fire TV app
LocalizedStringTypestring with attributesA string with the addition of the language, territories, and default attributes.
MimeTypeimage/jpeg, image/pngImage formats. JPEG for photos and backgrounds, PNG for logos with transparency.
OriginalBroadcastTypeFull Power Broadcast, Low Power Broadcast, Cable Only, Satellite, Over the Top, Network, TV, VOD, Radio, Digital Broadcast Network, SplitThe type of broadcast the station provides. An example of Split is full power broadcast during the day and low power broadcast at night.
PictureColorEnumTypecolor, bandw, colorized, composite, unknownPicture color characteristics:
  • color – Color picture
  • bandw – Black and white
  • colorized – Colorized from black and white
  • composite – Mixed
  • unknown – Unknown picture color
PolicyFilterTypeallow_all, allow_only, block_onlyGeographic filters for postal codes:
  • allow_all – Allows all postal codes in the region regardless of the PostalCode list.
  • allow_only – Allows only the postal codes listed in the PostalCode elements.
  • block_only – Blocks only the postal codes listed in the PostalCode elements.
ReleaseTypetheater, video, streamingDistribution mechanism for the release:
  • theater – Available in movie theaters
  • video – Available through physical media such as Blu-ray, DVD, or digital download
  • streaming – Available through a VOD service without a perpetual license
ResolutionType8K, 4K, FullHD, HD, SDVideo resolution levels in descending order of quality.
SourceDateTypeYYYY-MM-DDRepresents the date that the provider in the sourceName attribute delivered the data. Restricted to DateType format.
SourceIdTypestringThe identifier associated with this piece of data, provided by the source in the sourceName attribute.
SourceNameTypestringThe name of the provider of the metadata contained in this element.
TerritoriesTypeISO 3166-1 alpha-2Country codes, comma-separated.
Examples: US, US,CA,MX, GLOBAL.
Common codes: US, CA, MX, GB, DE, FR, ES, IT, JP, AU, BR, IN.
Last modified on May 28, 2026