A usual requirement of client UI applications is to retrieve live content metadata, either in full to populate a grid/list guide, or to enhance and extend metadata retrieved from the broadcast stream itself.
The requests required and how the data is used will depend on the requirements of the deployment. Some deployment examples are as follows:
STB client retrieves the channel list and a few days of event data from a broadcast stream (for example, DVB-C). The event data should be enhanced and extended to have, for example, a 30 day EPG with rich metadata.
OTT STB or open device needs to retrieve the complete channel list, subscription information, and event data OTT from the OpenTV Platform.
An open device acting as a companion device to a Gateway STB retrieves the channel list from the gateway, but needs to retrieve all event data and subscription data from the OpenTV Platform.
Data models
The basic data models involved in these use cases are described below. All this data can be found in the Metadata Server (MDS). Product subscription data is found in the Service Delivery Platform (see Subscription data).
Service
Also known as a Channel, a service represents a broadcast channel and contains metadata about the channel, such as channel number, network location (for example, CDN url for OTT), name, and logo url. A service can contain one or more technical entities, which represent the different delivery mechanisms available such as broadcast and adaptive OTT streams.
Service data model
Name
Type
Description
Localised
Always available
_id
String
Internal identifier for the object.
No
Yes
active
Boolean
Whether the channel is active.
No
Yes
CarryingNetwork
Array of strings
List of values representing the list of DVB triplets linked to this channel. The decimal value calculation according to DVB triplet is customer dependent.
No
Yes
catchUpSupport
Boolean
Whether the operator supports catch-up events on this channel.
No
Yes
Categories
Array of strings
A list of keywords classifying the content of the channel. CMS supports these keywords:
Action
Action-Adventure
Adult
Adventure
Children
Comedy
Documentary
Drama
EnEspanol
Family
Horror
International
Kids-Family
Library
NewRelease
Romance
ScienceFiction
SciFi-Horror
Sport
Suspense
Suspense-Thriller
ThreeDayRental
Thriller
Uncensored
War
No
No
companyId
String
The ID of the broadcaster company to which the channel is attached.
This field is not required, but the CMS always populates it.
No
No
Description
String
A description of the channel, from the CMS Service EPG key Description.
Yes
No
drmInstanceName
String
A name that uniquely identifies the DRM system that manages access to this channel. For channels protected by CAS (not DRM), this attribute is not present.
No
No
drmId
String
The identifier of the channel used by the DRM system that managies access to this channel. Values of drmId will only be unique within a particular DRM instance. A drmId value will always be present when a drmInstanceName value is supplied. For channels protected by CAS (not DRM), this attribute is not present.
No
No
id
String
The CMS's identifier for the object.
No
Yes
locale
String
The locale used for the object's localisable fields.
No
No
longName
String
The channel’s long name, for example, “The Biography Channel”.
This field is not required, but the CMS always populates it.
This field is not localised. Multi-language clients should use the Title field instead.
No
No
NetworkLocation
String
The location of the A/V stream of the channel on the network. For adaptive streaming, this will be the channel's URL. In case of Harmonic OS, the value must be of the form:
Used to pass data directly from the operator to the end-user device without any CMS/SDP processing. One possible use is to pass a list of keyword/value pairs, separated by semi-colons.
No
No
profileRef
String
The identifier of the profile that applies to this channel.
No
No
PromoImages
Array of strings
A list of promo image URLs for the channel. The Metadata Server does not validate the format of this field’s value, and does not attempt to access the URLs to verify the existence of the image files.
No
No
productRefs
Array of strings
A list of the IDs of the products that offer this channel.
No
No
provider
String
The identifier of the metadata provider, from the id of the export's CMSBtvData element.
Localised name for the rating, for example, Adult or Adulto.
Yes
Yes
shortName
String
A short name for the channel, or its call letters.
No
No
startOverSupport
Boolean
Whether the operator supports start-over events on this channel.
No
Yes
Title
String
The full name of the channel.
The CMS mandates that this field will be populated for at least one locale-form of each channel.
Yes
No
tvChannel
Integer
The channel number to be presented to the end user.
No
Yes
type
String
Present on an editorial channel. If the channel originates from the CMS ingest this will be set to BTV.
No
Yes
xml
String
The type of object. Always editorial.
No
Yes
nls.Title
String
Native language support for the title field. Allows correct sorting for a language, rather than relying on utf-8 ordering for sort.
Yes
No
9 reads
Programme
Also known as an Event, a programme represents a content item shown on a specific channel at a specific point in time (its schedule/period). Its metadata contains its schedule information, which channel it is on, if it's available as catchup or start-over, and usually duplicates most of its parent content information.
Programme data model
Name
Type
Description
Localised
Always available
_id
String
Internal identifier for the object.
No
Yes
Actors
Array of strings
The actors associated with the programme.
No
No
Aspect
String
The aspect ratio. Examples:
4:3
16:9Widescreen
No
No
Audio
Array of strings
A list of “locale-type” patterns representing the audio streams available for this content.
Localised text representation of the index of the episode in the series. This field is used to display the episode number. For example:
Season3, Episode 2
Yes
No
eventId
Number
The ID of the scheduled programme.
No
No
id
String
The CMS's identifier for the object.
No
Yes
isCatchUp
Boolean
Whether the time-shift “catch-up” function is available for this event.
No
No
IsRecordable
Boolean
Whether the end user is allowed to record this series.
No
No
isStartOver
Boolean
Whether the time-shift “start-over” function is available for this event.
No
No
IsTimeshifted
Boolean
Whether the programme is a time-shifted broadcast of an earlier programme. Typically used for "+1 hour" channels.
No
No
Language
String
The original language of the content (three-letter ISO language code).
No
No
locale
String
The locale used for the object's localisable fields.
No
Yes
nls.Title
String
The native language support for the title field – allowing for sorting according to the native language, rather than utf-8 order, as would be done through the Title field itself.
Yes
No
period
JSON object (see below)
Details of the broadcast schedule for this programme.
No
Yes
period.duration
Number
The length of time this item will appear in the catalogue, in seconds. If not supplied, the duration is omitted, not calculated.
No
No
period.end
String: a date and time in ISO 8601 format
The end time of the broadcast event.
No
Yes
period.providerId
String
The identifier of the metadata provider, from the ID of the export's CMSVodData element.
No
Yes
period.start
string: a date and time in ISO 8601 Sormat
The start time of the broadcast event.
No
Yes
PrivateMetadata
String
Generic field used to pass directly data from the operator to the end-user device without any processing. One possible use is to pass a list of keyword/value pairs separated by semi-colons.
No
No
Producers
Array of strings
The producers associated with the programme.
No
No
productRefs
Array of strings
The CMS IDs of the products that provide access to this programme.
No
No
profileRef
String
The CMS ID of the encoding profile that applies to this asset.
No
No
PromoImages
Array of strings
The URLs of promo images. Must be composed of URL-safe characters only.
No
No
provider
String
The identifier of the metadata provider, from the id of the export's CMSBtvData element.
No
Yes
Rating.code
String
Parental rating code (from CMS).
No
Yes
Rating.name
String
Localized name for the rating, for example, Adult or Adulto.
Yes
Yes
Rating.precedence
Integer
Quantitative rating value.
No
Yes
RecommendedProgrammeIds
Array of strings
The CMS programme IDs recommended for this programme (information taken from a recommendation engine or from the customer) with rank (a positive integer, where a higher number means a stronger recommendation) using the following pattern:
<ProgrammeId>/<Rank>
A referenced programme might be scheduled before or after the current one, and might be on a different channel.
No
No
RecommendedVodItemIds
Array of strings
The CMS VodItem IDs recommended for this programme (this information comes from the recommendation engine or from the customer) with rank (a positive integer, where a higher number means a stronger recommendation) using the following pattern:
<VodItemId>/<Rank>
No
No
serviceRef
String
The CMS ID of the channel carrying the programme.
No
Yes
ShortTitle
String
The short form of the title of this programme. Indended for use on devices with limited space.
Yes
No
SOCU_filename
String
Name of the asset file when this event is available via catch-up or start-over functionality.
No
No
Studio
String
The name of the owner of the content broadcast in this programme.
No
No
Subtitles
String
A list of “locale-type” patterns representing the subtitle streams available for this content.
This field is not localised. Multi-language clients should use the Title field instead.
No
Yes
Title
String
The title of the programme displayed to the user.
The CMS mandates that this field will be populated for at least one locale-form of the asset.
Yes
No
type
String
The domain of the object, always btv in this case.
No
No
xml
String
The type of the object. In this case, always Programme.
No
Yes
Year
String
The year of production of the content.
No
No
19 reads
Content
The Content represents a content item that is broadcast. It contains metadata such as the content title, description, episode number, actors, and definition. It also includes a link to its parent Series entity if such information exists for the content. If live content is also available as catchup or start-over, it can include one or more technical entities that contain media information, which represent the different available delivery mechanisms available for the catchup/startover.
Content data model
Name
Type
Description
Localised
Always available
_id
String
Internal identifier for the object.
No
Yes
Actors
Array of strings
List of actors.
No
No
Aspect
String
The picture ratio, for example, 16:9.
No
No
Audio
Array of strings
A list of locale-type patterns. For example:
"Eng-Standard",
"Eng-VisualImpaired"
No
No
AudioMode
String
The audio mode, for example, Mono or 5.1.
No
No
BestSalesIndex
Integer
Sales index for use in "Top" lists (for example, Top 10 Best Selling).
These are positive numbers, starting at 1.
No
No
Categories
Array of strings
A list of categories.
No
No
ContentType
String
Free text. Used for implementation-specific data.
No
No
CopyProtections
String
A list of rules for controlling certain hardware products.
No
No
Copyright
String
Copyright.
No
No
Countries
Array of strings
A list of countries.
No
No
CUEndDate
Date
End date of period during which recorded content can be seen in nPVR.
No
No
CUStartDate
Date
Start date of period during which recorded content can be seen in nPVR.
NLS version of title to allow for correct sorting of items.
No
No
PrivateMetadata
String
Generic field to pass directly data from customer to end-user device.
No
No
Producers
Array of strings
List of producers.
No
No
profileRef
String
The encoding profile ID.
No
No
ProgrammeEndDate
Date
If content is catch-up, this contains the end time of the corresponding event.
No
No
ProgrammeStartDate
Date
If content is catch-up, this contains the start time of the corresponding event.
No
No
PromoImages
Array of strings
A list of promo image URLs.
No
No
promoRefs
Array of strings
The list of promotion IDs.
No
No
provider
String
Provider-related identifier.
No
Yes
Rating.code
String
Parental rating code (from CMS).
No
Yes
Rating.name
String
Localised name for the rating, for example, Adult or Adulto.
No
Yes
Rating.precedence
Integer
Quantitative rating value.
No
Yes
Scoring
Integer
Score of the content/episode.
No
No
seriesRef
String
Identification of parent series.
No
No
ServiceLongName
String
If content is catch-up, this contains the service long name of the corresponding event.
No
No
ShortTitle
String
The short name of the content.
Yes
No
Subtitles
String
A list of "locale-type" mappings, for example:
Eng-Standard
No
No
Studio
String
The content owner.
No
No
Synopsis
String
The synopsis of the content.
Yes
No
title
String
Unique identifier of the content (duplicated across locales though).
No
Yes
Title
String
The name of the content.
Yes
Yes
TotalDownloads
Integer
Total number of downloads of the content/episode.
No
No
ViewingCounter
Integer
Number of times a piece of content has been viewed.
No
No
ViewingNumber
Integer
Number of times a user can see the content once purchased.
No
No
Year
Integer
Year of production.
No
No
21 reads
Series
The Series represents a collection of Content items that belong together, either representing a Season or the whole Series (but currently not both). The Series contains metadata such as a description and promotional image information. It also acts as a link for all related content. Not all content items will have a series, and some deployments do not provide this information at all.
Series data model
Name
Type
Description
Localised
Always available
_id
String
Internal identifier for the object.
No
Yes
Actors
Array of strings
A list of actors. For example:
"Tom Cruise",
"Nicole Kidman"
No
No
Aspect
String
The aspect ratio, for example, 16:9 or Widescreen.
No
No
Audio
Array of strings
A list of "locale-type" patterns representing the audio streams available for this series.
The audio mode. For example, Mono, SRS, THX, 5.1, Nicam Stereo, or Dual Mono.
No
No
BestSalesIndex
Integer
Sales index (position) for use in "Top" lists (for example, Top 10 Best Selling).
These are positive numbers, starting at 1.
If -1 or not present, this series is not in any "Top n" index.
No
No
Categories
Array of strings
A list of operator-defined category or genre names for this series.
No
No
ContentType
String
Free text. Used for implementation-specific data.
No
No
CopyProtections
String
A list of usage rules for controlling certain hardware outputs to prevent unauthorised content copying.
For example:
"CGMS-A",
"HDCP"
If the value is 0 or not present, there is no restriction.
No
No
Copyright
String
A copyright message.
No
No
Countries
Array of strings
A string of two-letter ISO codes representing countries relevant to this series.
No
No
Definition
String
The video definition. One of HD, SD, or 3D.
No
No
Description
String
The description of the series.
Yes
No
Directors
Array of strings
A list of directors.
No
No
DvbCategories
Array of strings
Array of DVB genres and sub-genres.
No
No
Episode
String
Episode text string.
Yes
No
IsRecordable
Boolean
Whether the end user is allowed to record this series.
No
No
Language
String
The original language of the series (three-letter ISO language code).
No
No
nls.Title
String
Native language support for the title field, which allows it to be sorted correctly in the local languare rather than using UTF-8 ordering.
PrivateMetadata
String
Generic field used to pass data directly from the operator to the end-user device without any processing. One possible use is to pass a list of keyword/value pairs.
No
No
Producers
Array of strings
A list of producers.
No
No
PromoImages
Array of strings
A list of promo image URLs. Must contain only URL-safe characters.
No
No
provider
String
The identifier of the metadata provider, from the id of the export's CMSVodData element.
This field is not localised. Multi-language clients should use the Title field instead.
No
Yes
Title
String
The name of the series.
The CMS mandates that this field will be populated for at least one locale-form of the asset.
Yes
Yes
TotalDownloads
Integer
Total number of downloads of the series (or of episodes within the series, according to the operator's preference).
No
No
ViewingCounter
Integer
Number of times a piece of content has been viewed.
No
No
ViewingNumber
Integer
How many times a user can watch the series (or episodes within it) once purchased. If 0 or not present, there is no limitation.
No
No
Year
Integer
The year of production of the content.
No
No
8 reads
Product
A live content product is the same as an on-demand product; it makes content available for a length of time for a specific price. The metadata includes details such as product availability, price, currency and type. A product can be linked to any number of channels or events. Likewise, an event or channel could be linked to any number of products, though it is expected that each product has a different offering, for example, different product types or content.
There are two product types:
Subscription
Transaction
Product data model
Name
Type
Description
Localised
Always available
_id
String
Internal identifier for the object.
No
Yes
businessProductRefs
Array of strings
List of IDs referring to parent "business products".
Since MDS 1.1STD4.
No
No
businessProductType
String
A numeric value provided by the CAS to classify the type of product.
No
No
casInstanceName
String
The name that uniquely identifies the CAS server that manages access to this channel or event.
No
No
casId
String
The identifier of this product within the CAS. This is the technical ID for all conditional-access-related operations.
For the NAGRA CAS, this ID is a numeric value with up to 12 digits.
No
No
casMopId
String
The MOP ID assigned by the NAGRA CAS to this product, if applicable. The presence of this value depends on the CAS features activated for the customer project.
No
No
endPurchase
String: a date and time in ISO 8601 format
The end date and time of the period when the end user may purchase this product.
No
No
endValidity
String: a date and time in ISO 8601 format
The end date and time of the period when this product is valid. Access to the content/event sold by this product is not allowed after this time.
No
No
id
String
The CMS's identifier for the object.
No
Yes
impulsive
Boolean
Whether the product can be acquired by the end-user “impulsively”, that is, without requiring a right to be delivered explicitly from the head-end.
CMS 4 always sets this field to true.
No
No
isSOCU
Boolean
Whether start-up and catch-up can be used with this content.
For PPV and subscription products, the default is configured in the CMS. For other products, the default value is false.
No
No
locale
String
The language of the profile.
Yes
Yes
ordering
Boolean
Whether the product be acquired by the end-user in “ordering” mode, that is, via a right delivered from the head-end.
CMS 4 always sets this field to false.
No
No
price
Sub-object
The price this product can be purchased for.
MDS currently only supports one price in one currency per product.
No
No
price.currency
String
The currency the price is in.
No
Yes
price.endPurchase
String: a date and time in ISO 8601 format
The end date and time of the period when the end user may purchase the product at this price.
No
No
price.providerId
String
The identifier of the metadata provider, from the id of the export's CMSBtvData.
No
Yes
price.value
Number
The value of the price in the specified currency.
No
Yes
price.startPurchase
String: a date and time in ISO 8601 format
The start date and time of the period when the end user may purchase the product at this price.
No
No
PrivateMetadata
String
Used to pass data directly from the customer to the end user device without any processing.
One possible use is to pass a list of keyword/value pairs separated by semi-colons.
No validation is done by the Metadata Server on the value of this field.
No
No
ProfileName
String
Allows a product to be associated to an externally-managed profile.
No
No
providerId
String
The identifier of the metadata provider, from the id of the export's CMSBtvData element.
No
Yes
startPurchase
String: a date and time in ISO 8601 format
The start date and time of the period when the end user may purchase this product.
No
No
startValidity
String: a date and time in ISO 8601 format
The start date and time of the period when this product is valid. Access to the content/event sold by this product is not allowed before this time.
No
No
title
String
The name of the product.
This field is not localised. Multi-language clients should use the TitleForProduct field instead.
No
Yes
TitleForProduct
String
The name of the product.
Yes
No
type
String
The type of product. Either single orsubscription.
single products reference only one broadcast event.
subscription products reference multiple events, payable as a recurring subscription.
No
Yes
xml
String
The type of object. Always Product.
No
Yes
12 reads
Subscription product
A subscription product is a product that typically has no predefined end date, and incurs a recurring charge on an account for continued access. Access to content contained within only stops if subscription to the product is cancelled or the content stops becoming available within the product.
The typical use case for subscription products in the context of live content is to give access to one or more channels. This product will usually also give access to any start-over or catchup on-demand content that is linked to the subscribed channel.
Transaction product
A transaction product is a product that gives access to content for a specific length of time for a single charge. It can include any number of content items.
The typical use case for transaction products in the context of live content is for Pay-Per-View (PPV) events.
Model graph
The following diagram shows the links between the various models within MDS. Each model is grouped within the API by which it can be accessed.
Use cases
Subscription information: Use cases regarding retrieval of subscription information is covered in Subscription data.
Retrieving a channel list
A list of channels can be retrieved using the MDS Services API. Refer to the MDS API reference, open the document corresponding to the Metadata delivery API and go to the '/metadata/delivery/btv/services' section.
Retrieving all channels
All channels can be retrieved by not specifying a channel filter. For example:
This will request the list of all channels with an "en_gb" locale, ordered by Title, with only the Title and tvChannel (channel number) field returned. A locale must be specified to retrieve the data in that language. If no locale is specified, the system default is used. Only the first 10 channels will be returned due to the limit. The next 10 can be returned by specifying offset=10&limit=10.
Retrieving subscribed channels
First retrieve the broadcast subscription products applicable for the account, as described in Subscription data.
Collate the product identifiers together into an array, and pass it as a productRef filter. For example:
A list of events can be retrieved using the MDS Programmes API. Refer to the MDS API reference, open the document corresponding to the Metadata delivery API and go to the '/metadata/delivery/btv/programmes' section.
Retrieving events for an EPG window
In this use case we want enough EPG data to render an EPG screen with 8 channels and a 3 hour window (for example, the user can see from 10 AM to 2PM).
For the purpose of optimisation, the events should be retrieved per channel. In the example below we ask for events on BBC1, with a start time before 2PM on Oct 29th but after 2PM on Oct 28th. This restriction on starting after 24 hrs earlier reduces the work the MDS needs to do when filtering on end time. We then specify events ending after 10AM. We specifically ask for only the Title, Description, Duration, Start, End, and Rating fields, as these are the only fields used to render the EPG. Paging is not necessary because we are already restricting the returned items by dates.
In this use case a user wants to view additional information about an event, such as show cast, episode data, technical information, and so on. Because we know the event in question, we can specify its unique id in the request and no other filter is necessary. To retrieve the additional information we need to render the UI, we specify further fields. Because we already have the information for "id", "Title", "Description", and so on, we don't need to retrieve them again, only the additional data.
Retrieving live content to show a content-first view
When retrieving events for the purpose of rendering an EPG, a schedule-first view is required. Some UI applications might also have a content first view, where a user browses the content available before discovering its schedule. Or the user might want to find out when a show is repeated.
To enable this functionality in an efficient way, an MDS BTV editorials API is provided. This structures the response so that the content returned includes the schedules, rather than the other way around (which is a less efficient structure for this use case).
Refer to the MDS API reference, open the document corresponding to the Metadata delivery API and go to the '/metadata/delivery/btv/editorials' section.
Editorial content is not always available: Live TV editorial content is only made available if the data provided by the content provider links the scheduled programmes with their content. If this link is missing, the editorials API will have no data.
Retrieving all schedules for a particular content
The following example can be used to retrieve all schedules for a particular content (using the editorial.id):
If channels or programmes have any related products, the identifiers for those products are returned in the productRef field. For channels, if the productRef list is empty, the channel is free-to-air (FTA). If a programme productRef list is empty, it means that the programme is included with the access to its channel, be that FTA or not. If the channel or programme does have associated products, it can be assumed that one of the products must be purchased/subscribed for access to that channel.
A request to the MDS BTV products API should be made when you need to display the product information.
Refer to the MDS API reference, open the document corresponding to the Metadata delivery API and go to the '/metadata/delivery/btv/products' section.
Retrieving product information for a channel or event
Pass in the productRef from the service or programme as the id in the products API.
Series information can be used to group episodes of a series together, both for display purposes and for PVR series linking. Series information is available only if the Content metadata is available.
Retrieving series information for a content item
The series information can be retrieved by using the MDS BTV Series API. Pass in the seriesRef value as the id into the Series API.
Refer to the MDS API reference, open the document corresponding to the Metadata delivery API and go to the '/metadata/delivery/btv/series'section.
