TOC 
Working DraftA. Reggiori
 Derrick Media
 May 21, 2013


Portable Listings

Abstract

This document specifies Portable Listings, a JSON document format and API for accessing audiovisual content metadata over HTTP.



Table of Contents

1.  Notational Conventions
2.  Definitions
3.  Introduction
    3.1.  Goals
    3.2.  Approach
    3.3.  Feedback
4.  Workflow Overview
5.  Discovery
6.  Listings API
    6.1.  Requesting Specific Information
    6.2.  Query Parameters
        6.2.1.  Filtering
        6.2.2.  Sorting
        6.2.3.  Pagination
        6.2.4.  Presentation
        6.2.5.  Declining to honor query parameters
    6.3.  Response Format
    6.4.  Error Codes
    6.5.  Authentication and Authorization
        6.5.1.  Delegated Authorization
        6.5.2.  Direct Authorization
        6.5.3.  Available Authorization Methods
7.  Listings Format
    7.1.  Basic Structure
        7.1.1.  Fields
        7.1.2.  Links
        7.1.3.  Relationships
    7.2.  Multilingual Fields
    7.3.  Interoperability Considerations
    7.4.  Referencing Profiles
8.  Core Profile
    8.1.  Reference Data
    8.2.  Profile Identifier
    8.3.  Additional Link Relation Types
        8.3.1.  "promotional-information"
        8.3.2.  "review"
        8.3.3.  "highlights"
        8.3.4.  "screenplay"
        8.3.5.  "transcript"
        8.3.6.  "shot-list"
        8.3.7.  "edit-decision-list"
        8.3.8.  "rundown"
        8.3.9.  "dopesheet"
    8.4.  Object Types
        8.4.1.  Entry
            8.4.1.1.  Fields
            8.4.1.2.  Links
            8.4.1.3.  Relationships
        8.4.2.  Category
            8.4.2.1.  Fields
            8.4.2.2.  Relationships
        8.4.3.  Content
            8.4.3.1.  Fields
            8.4.3.2.  Links
            8.4.3.3.  Relationships
        8.4.4.  Programme
            8.4.4.1.  Fields
            8.4.4.2.  Relationships
        8.4.5.  Programme Group
            8.4.5.1.  Relationships
        8.4.6.  Brand
        8.4.7.  Series
        8.4.8.  Programme Item
            8.4.8.1.  Relationships
        8.4.9.  Episode
        8.4.10.  Clip
        8.4.11.  Version
            8.4.11.1.  Fields
            8.4.11.2.  Relationships
        8.4.12.  Service
            8.4.12.1.  Fields
            8.4.12.2.  Links
            8.4.12.3.  Relationships
        8.4.13.  Programme Publication
            8.4.13.1.  Fields
            8.4.13.2.  Relationships
        8.4.14.  Broadcast
            8.4.14.1.  Fields
        8.4.15.  Ondemand
            8.4.15.1.  Fields
        8.4.16.  Schedule
            8.4.16.1.  Fields
            8.4.16.2.  Relationships
        8.4.17.  Catalogue
            8.4.17.1.  Fields
            8.4.17.2.  Relationships
        8.4.18.  Application
            8.4.18.1.  Fields
            8.4.18.2.  Relationships
        8.4.19.  Application Build
            8.4.19.1.  Fields
            8.4.19.2.  Relationships
        8.4.20.  Application Publication
            8.4.20.1.  Fields
            8.4.20.2.  Relationships
        8.4.21.  Application Gallery
            8.4.21.1.  Relationships
        8.4.22.  Media Resource
            8.4.22.1.  Fields
        8.4.23.  Media Group
            8.4.23.1.  Relationships
        8.4.24.  Segment
            8.4.24.1.  Fields
            8.4.24.2.  Relationships
        8.4.25.  Segment Group
            8.4.25.1.  Relationships
        8.4.26.  Content Collection
            8.4.26.1.  Relationships
        8.4.27.  Rights
            8.4.27.1.  Fields
            8.4.27.2.  Relationships
        8.4.28.  Award
            8.4.28.1.  Fields
            8.4.28.2.  Relationships
        8.4.29.  Agent
        8.4.30.  Person
        8.4.31.  Organisation
            8.4.31.1.  Relationships
        8.4.32.  Group
            8.4.32.1.  Relationships
9.  IANA Considerations
10.  Security Considerations
11.  Acknowledgements
12.  Change Log
13.  References
    13.1.  Normative References
    13.2.  Informative References
Appendix A.  Examples
Appendix B.  Compatibility with EBUCore and other standards
§  Author's Address




 TOC 

1.  Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119] (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.).



 TOC 

2.  Definitions

Audiovisual Content:
Or more simply Content throughout the scope of this document, it refers to the actual intellectual or artistic piece of material such as a Television Programme, Feature Film, Music Video, Advert etc.
Content Metadata:
It is structured information that describes, explains, locates, or makes it easier to retrieve, use, or manage a piece of audiovisual content. Examples of metadata records include detailed information about a television show episode (title, synopsis, series, brand, creator, contributor, release date, etc.), a film (title, synopsis, genre, year, duration, etc.), an advert on television (title, advert brand, advert product, advert code, product code etc.), a broadcast event on a television schedule (broadcast service name, start/end time, country, language, etc.) and so on. More specifically a piece of Content Metadata is being represented with the "Content" object type throughout the scope of this document (see Section 8.4.3 (Content)).
Entry Metadata:
Or meta-metadata, it is system information which is used to support the storage and retrieval of actual Content Metadata itself (e.g. updated, metadataPublisher). Throughout this document we will clearly distinguish the "Entry Metadata" and "Content Metadata" and we will provide additional text to clarify the context of a specific piece of metadata, where and if necessary.
Listings:
Or listings information, it is a term used in this document as a more colloquial and less technical synonym for the information being stored and search by a Provider. More specifically the term listings might refer to a specific list of results (result set) returned by a Service Provider, which includes both the Content Metadata and any Entry Metadata. For example, one could talk about television listings information, listings of people contributing to a film, a listings of showing times of a film, a listings of upcoming DVDs releases, a listings of scenes of a film and so on.
Content Language/Length/Type:
These terms they are generally used to refer to the language, length in bytes and the type of the metadata Entry, as returned in an HTTP request header. Where and if necessary we will clarify when the term language, type or length will refer to the actual piece of Audiovisual Content.
Service Provider:
A Web application that provides listings information via the Portable Listings protocol.
Consumer:
A Web site or application that uses the Portable Listings protocol to request listings information managed by the Service Provider.
Base URL:
The root endpoint URL specified by the Service Provider during Discovery and used to make requests. Consumers MAY append additional path information and query string parameters to this URL as part of the request.
Entry:
An individual item object (or result) part of a result set (listings) returned by a Service Provider. Entries are represented in a result set with the entry element. An entry has one or more fields and relationships associated to it.
Singular Field:
An Entry field that can appear at most once per Entry, e.g. displayName or id.
Plural Field:
An Entry field that can appear multiple times per Entry, e.g. keywords or tags.
Simple Field
A Singular Field or Plural Field whose value is a single string attribute (see Section 7.1 (Basic Structure)).
Complex Field
A Singular Field or Plural Field whose value is an object containing multiple sub-field attributes (see Section 7.1 (Basic Structure)).
Canonical Value:
Specified string values for string-valued Entry fields that represent common values in a canonical form. For example alternativeTitle field MAY have a type of "original", "working" etc. Service Providers SHOULD conform to Canonical Values if appropriate, but MAY deviate if they need to represent additional values (see Section 8.1 (Reference Data)).
Primary Sub-Value:
The sub-field in a Complex Field that should be used when sorting or filtering by that field. Unless otherwise specified, the value sub-field is always the Primary Sub-Field.
Singular Relationship:
An Entry relationship which link to another Entry via a well-known named relationship and that can have at most one value, e.g. a programme service.
Plural Relationship:
An Entry relationship which link to another Entry via a well-known named relationship and that can have multiple values, e.g. a series programmes.
Sub-Entry:
An Entry which is related to another entry via a well-known relationship.
Source Entry
Or Relationship Context, it is the Entry from which a named and directed Relationship is created to a Target Entry.
Target Entry
A Target Entry is the Sub-Entry target of a Relationship from a Source Entry. A Target Entry can play one or more Roles with a given Source Entry.
Sub-Entry Role
The role played by the Target Entry in a Relationship with a given Source Entry is defined to be the name or label of the relationship itself.
Profile:
A particular format (or schema) for the various Entries per [RFC6906] (Wilde, E., “The 'profile' Link Relation Type,” March 2013.). In the scope of this specification a profile is expressed using an atomic set of data modelling rules as defined in Section 7.1 (Basic Structure). The core profile is integral part of this specification as defined in Section 8 (Core Profile).



 TOC 

3.  Introduction

This document specifies Portable Listings, a document format and API to easily provide secure access to audiovisual content metadata and related information over the Web.

The specification defines a general framework, access patterns and portable format for holding and retrieving a variety of audiovisual content metadata using simple entity types, containers, attributes and relationships. For example, using Portable Listing a Consumer can request information from a Service Provider about television series and episodes information, music videos, film reviews, showing times, casts, crews, video technical details, subtitles, trailers etc. Mechanisms are defined to specify alternative languages and refer to related metadata and resources. This document also defines the procedure by which particular audiovisual content metadata formats, called profiles, for carrying application-specific information can be defined and referenced, and the conventions such formats must follow. It is expected that other specifications will be produced that define such formats for various applications.

This specification also defines and adds the following additional link relation types to the "Link Relations" registry established by [RFC5988] (Nottingham, M., “Web Linking,” October 2010.): "promotional-information", "review", "highlights", "screenplay", "transcript", "shot-list", "edit-decision-list", "rundown" and "dopesheet".



 TOC 

3.1.  Goals

The goal of Portable Listings is to make it easier for developers to give their users a secure way to access audiovisual content metadata and related information over the web. Specifically, we seek to create:



 TOC 

3.2.  Approach

Our design is focused around ease of adoption, which means a few things:

  1. First, our emphasis is on simplicity of design and targeted use cases, keeping our scope intentionally narrow at the outset. For example, this document is simply about access, and defers for now on the more complex issues around update and sync.
  2. Second, we're taking a modern approach to audiovisual content metadata description by unifying traditional and more Web oriented data, in order to properly represent the current diversity of television, brodcasting and Web ecosystems.
  3. Third, we're leveraging and reusing existing broadcast and television industry standards and semantics wherever possible, including the EBUCore Metadata Set [EBUCORE] (EBU, “EBU – TECH 3293 - EBU Core Metadata Set (EBU Core) v.1.4,” .), TV-Anytime [TV‑ANYTIME] (ETSI, “TV Anytime,” .), the BBC Programmes Ontology [BBC‑PROGRAMMES] (BBC, “Programmes ontology,” .) and [HTML5] (W3C, “HTML5 - A vocabulary and associated APIs for HTML and XHTML,” .) Video and Media Multitrack [HTML5‑MM] (W3C, “Media Multitrack API,” .). This document is heavily grounded on previous work done on the Portable Contacts [PortableContacts] (Smarr, J., “Portable Contacts 1.0 Draft C,” .) and related specifications.
  4. Fourth, we designed the specification to be extensible and pluggable where additional information and functionality can be easily added by Service Providers as needed.
  5. And lastly, we're designing something that should be easy for current service providers to adopt. We started with a review of all the major existing television, broadcast, Web and Social media standards and APIs and targeted common capabilities that they all share and provide. We believe this pragmatic balance is the best and quickest way to achieve our intended goal of widespread adoption.



 TOC 

3.3.  Feedback

The Portable Listing specification is currently being developed on the http://groups.google.com/group/portablelistings mailing list. Feedback can be posted to the Portable Listings list or directly to the author. If you encounter any problems with joining the list, please contact the author. If you refer or discuss any further about Portable Listings on Twitter or Facebook the hash tag #poli or #portablelistings MAY be used.



 TOC 

4.  Workflow Overview

A Consumer wishing to access a Provider's metadata via Portable Listings must start with an Initial Identifier for the Service Provider containing the Provider's metadata. In many cases, this may be the domain name of the Service Provider's web site, such as sample.site.org, but may be a more specific URL. Consumers then perform Discovery on the Initial Identifier to determine where the Portable Contacts endpoint for this Service Provider resides. If successful, the Consumer may then attempt to request information from that endpoint. If the endpoint contains private metadata, the Service Provider will return an authorization challenge, and the Consumer must then guide the user through an appropriate authorization flow to obtain the credentials necessary to access this private metadata. Upon successful authorization, the Consumer may request metadata from the Portable Listings endpoint using these authorization credentials. Whether accessing public or private metadata, Consumers may request a specific subset of the Provider's metadata using standard Query Parameters. Upon a successful request, the metadata is returned in the response, and the Consumer may then parse the response metadata and use it as desired. The following sections detail each of these steps.



 TOC 

5.  Discovery

Discovery serves both to signal that a Service provider is Portable Listings enabled and provide the Portable Listings API endpoint(s) to which requestes may be sent. It relies on link endpoint discovery per [RFC5988] (Nottingham, M., “Web Linking,” October 2010.) for feeds and HTML pages, and discoverable URIs per LRDD [HOSTMETA] (Eran Hammer-Lahav, E., “Web Host Metadata,” .), [WEBFINGER] (, “The Webfinger Protocol,” .), and [XRD] (, “Extensible Resource Descriptor (XRD) Version 1.0 - Committee Draft 02,” .).

The API is identified by the Service Type http://portablelistings.net/spec/1.0 and the corresponding URI is the Base URL for the API. The Base URL MUST NOT contain any query string, as additional path information and query string variables MAY be appended by Consumers as part of forming the request (as described in detail below).

An example XRD document describing the availability and location of a Portable Listings endpoint might look like this:

<XRDS xmlns="xri://$xrds">
  <XRD xmlns:simple="http://xrds-simple.net/core/1.0"
              xmlns="xri://$XRD*($v*2.0)" version="2.0">
    <Type>xri://$xrds*simple</Type>    <Service>
      <Type>http://portablelistings.net/spec/1.0</Type>
      <URI>http://sample.site.org/path/to/api/</URI>
    </Service>  </XRD>
</XRDS>



 TOC 

6.  Listings API

This first version of the specification excludes updates and focus on simple read-only invocation. All requests to the Service Provider are made as HTTP GET operations on a URL deriving from the Base URL specified in Section 5 (Discovery).

A request using the Base URL alone MUST return all content metadata Entries.

For example, by issuing this request:

GET /api/listings HTTP/1.1
Host: api.example.org

The following two Entries would be returned:

HTTP/1.1 200 OK
Content-Length: ...
Content-Language: en
Content-Type: application/listings+json

{
  "entry": [
    {
      "id": "5E5EEBED3173",
      "objectType": "episode",
      "displayName": "Episode 1",
      "title": "Pilot",
      "alternativeTitle": {
              "type": "original",
              "value": "Northwest Passage"
              },
      "summary": "The small northwest town of
                  Twin Peaks, Washington
                  is shaken when the body of
                  Laura Palmer, is discovered...",
      "contributor": [
        {
          "href": "C675EDD23A2D",
          "role": "director",
          "label": "David Lynch",
          "primary": true
        },
        {
          "href": "C675EDD23A2D",
          "role": "writer",
          "label": "David Lynch"
        },
        {
          "href": "2F050A9AF481",
          "role": "writer",
          "label": "Mark Frost"
        }
      ]
    },
    {
      "id": "8881860D6F31",
      "objectType": "episode",
      "displayName": "Episode 2",
      "title": "Traces to Nowhere",
      "summary": "Cooper's investigation into the
                  murder of Laura Palmer continues,
                  as her secret boyfriend James Hurley
                  is interrogated...",
      "contributor": [
        {
          "href": "3C67E1038205",
          "role": "director",
          "label": "Duwayne Dunham",
          "primary": true
        }
      ]
    }
  ]
}


 TOC 

6.1.  Requesting Specific Information

In addition to simple requests, Service Providers MUST recognize the following additional path information when appended to the Base URL:

For example, assuming the Service Provider has the information as listed in the previous example by issuing this request:

GET /api/listings/5E5EEBED3173 HTTP/1.1
Host: api.example.org

The following Entry would be returned:

HTTP/1.1 200 OK
Content-Length: ...
Content-Language: en
Content-Type: application/listings+json

{
    "entry": {
      "id": "5E5EEBED3173",
      "objectType": "episode",
      "displayName": "Episode 1",
      "title": "Pilot",
      "alternativeTitle": {
              "type": "original",
              "value": "Northwest Passage"
              },
      "summary": "The small northwest town of Twin Peaks,
                  Washington is shaken when the body of
                  Laura Palmer, is discovered...",
      "contributor": [
        {
          "href": "C675EDD23A2D",
          "role": "director",
          "label": "David Lynch",
          "primary": true
        },
        {
          "href": "C675EDD23A2D",
          "role": "writer",
          "label": "David Lynch"
        },
        {
          "href": "2F050A9AF481",
          "role": "writer",
          "label": "Mark Frost"
        }
      ]
    }
}

While instead by issuing this request:

GET /api/listings/5E5EEBED3173/contributor HTTP/1.1
Host: api.example.org

The following Entries would be returned:

HTTP/1.1 200 OK
Content-Length: ...
Content-Language: en
Content-Type: application/listings+json

{
    "entry": [
      {
        "id": "C675EDD23A2D",
        "objectType": "person",
        "displayName": "David Lynch",
        "name": {
          "middleName": "Keith"
        },
        "birthday": "1946-01-20"
      },
      {
        "id": "2F050A9AF481",
        "objectType": "person",
        "displayName": "Mark Frost"
      }
    ]
}


 TOC 

6.2.  Query Parameters

Portable Listings defines a standard set of operations that can be used to filter, sort, and paginate response results. The operations are specified by adding query parameter to the Base URL, either in the query string or as HTTP POST data. Providers MAY support additional query parameters not specified here, and Providers SHOULD ignore any query parameters they don't recognize.



 TOC 

6.2.1.  Filtering

Filtering is used to limit the request results to Entries that match given criteria. Results filtering is accomplished by combining the following request parameters:

filterBy:
Specifies the field name to filter by. If the specified field is a Plural Field, the Entry SHALL match if any of the instances of the given field match the specified criterion (e.g. if an Entry has multiple alternativeTitle values, only one has to match for the entire Entry to match). If a Simple Field is specified, its value must match the specified filterValue according to the specified filterOp. If a Complex Field is specified, its Primary Sub-Field must match. If the specified field is not a direct child of the entry element, the full path MUST be specified using the '.' character as separator. For example, to filter by gender the parameter value is gender and to filter by first name, the parameter value is name.givenName. Links SHALL be filtered using the filterLinksBy filter while relationships SHALL be filtered using the filterRelationshipsBy filter.
filterOp:
Specifies the comparison method used to evaluate the field value with the value of the filter criterion. Providers SHOULD support the following values:
  • equals: the two values must be identical strings.
  • contains: the entire filterValue must be a substring of the Entry field value.
  • startswith: the entire filterValue must be a substring of the Entry field value, starting at the beginning of the field value. This criterion is satisfied if the two strings are equal.
  • present: an Entry matches the criterion if the field specified by filterBy has a non-empty value, or if it contains a non-empty node for complex fields.
Providers MAY support additional filter operations if they choose. Providers MUST decline to filter results if the specified filter operation is not recognized (as per Section 6.2.5 (Declining to honor query parameters)).
filterValue:
Specifies the value to filter by, using the comparison method defined by filterOp.
filterObjectType:
Specifies a comma-separated list of object types as expressed in the Entry objectType field. A Service provider SHALL filter out any Entries not matching any of the requested object types. If the entry object type value is specified, all metadata Entries MUST be returned. This is also equivalent to providing no additional path info or query parameters on the Base URL.
filterDateBy:
Specifies the field name to filter by date. If filterDateOp is range and the upper date boundary field name is different from the lower boundary field name, a second field name SHALL be specified separated by comma (e.g. start,end). If the specified fields are Plural, Entries SHALL match if any of the instances of the given field match the specified criterion (e.g. if an Entry has multiple alternativeDate values, only one has to match for the entire Entry to match). If Simple Fields are specified, their value must match the specified filterDateValue according to the specified filterDateOp. If Complex Fields are specified, their Primary Sub-Field must match. The updated field SHALL be filtered using the updatedSince and updatedUntil filters.
filterDateOp:
Specifies the comparison method used to evaluate the date field values with the values of the date filter criterion. Providers SHOULD support the following values:
  • onThisDate: the date field value MUST be identical with the date filter criterion value.
  • before: the date field value MUST be less than the date filter criterion value.
  • after: the date field value MUST be greater than the date filter criterion value.
  • range: the lower boundary date field value MUST BE greater than or equal to lower boundary date filter criterion value, and the upper boundary date field value MUST BE less than or equal to the upper boundary date filter criterion value.
Providers MAY support additional date filter operations if they choose. Providers MUST decline to filter results if the specified filter operation is not recognized (as per Section 6.2.5 (Declining to honor query parameters)).
filterDateValue:
Specifies the value to filter by date, using the comparison method defined by filterDateOp. The value MAY be expressed as TIME, TIMESTAMP, YEAR or PERIOD as specified in Section 7.1.1 (Fields). If filterDateOp is range a second value SHALL be specified separated by comma (e.g. 2011-05-20,2011-05-21).
filterLinksBy:
Specifies a link name to filter Entries by (e.g. 'supportingMaterial'). A Service Provider SHALL match only Entries which have the given link name.
filterLinksType:
Specifies a link type to filter Entries by (e.g. 'review'). A Service Provider SHALL match only Entries which have a link type as specified in the rel sub-field matching the specified link type.
filterLinksValue:
Specifies a link target IRI to filter Entries by. A Service Provider SHALL match only Entries which have a link target as specified in the href sub-field matching the specified link target IRI.
filterPublisher:
Specifies the id of the metadata publisher as expressed in the metadataPublisher relationship. A Service Provider SHALL filter out any Entries not matching any of the requested metadata provider. If the @all value is specified, all metadata Entries MUST be returned irrespectively of the metadata publisher. This is also equivalent to providing no additional path info or query parameters on the Base URL.
filterRelationshipsBy:
Specifies a relationship label to filter Entries by (e.g. 'service'). A Service Provider SHALL match only Entries which have the provided relationship label. The metadataPublisher relationship SHALL be filtered using the filterPublisher filter.
filterRelationshipsType:
Specifies a relationship type to filter Entries by (e.g. 'related'). A Service Provider SHALL match only Entries which have a relationship type as specified in the rel sub-field matching the specified relationship type.
filterRelationshipsValue:
Specifies a relationship target identifier to filter Entries by. A Service Provider SHALL match only Entries which have a relationship target as specified in the href sub-field matching the specified relationship target identifier.

In addition, requests can filter results based on their "update" timestamp:

updatedSince:
Returns only Entries that have been modified on or after the given time, specified as an TIMESTAMP (see [RFC3339] (Klyne, G., Ed. and C. Newman, “Date and Time on the Internet: Timestamps,” July 2002.)). The filter is based on the value of the updated field, and can be used independently of other filters or combined. It enables a basic syndication pattern when accessing the same metadata over time. The first API call returns all metadata, which can be stored locally. Subsequent API calls can specify updatedSince with the time of the last API call, so that only Entries that have been added or modified since the last API call will be returned.
updatedUntil:
Returns only Entries that have been modified on or before the given time, specified as an TIMESTAMP (see [RFC3339] (Klyne, G., Ed. and C. Newman, “Date and Time on the Internet: Timestamps,” July 2002.)). Like for updatedSince the filter is based on the value of the updated field, and can be used independently of other filters or combined.

For example, given the content metadata of the sample request above and the parameters filterBy=title&filterOp=startswith&filterValue=Trac, only the second Entry (with id=8881860D6F31) would match and be returned. However, with parameters filterBy=title&filterOp=present, both Entries would be returned. Given the parameters filterBy=title&filterOp=contains&filterValue=lot, only the first Entry (with id=5E5EEBED3173) would match, as would it be the only Entry to match given the parameters filterBy=alternativeTitle&filterOp=present.

If a request specifies a filterValue but no filterBy or filterOp, it is up to the Service Provider how to interpret this filter request. Service Providers MAY choose to default to filtering by a given field (e.g. displayName); they MAY choose to implement a custom, Provider-specific query syntax for filterValue in this case; or they MAY choose to reject requests of this type.

In general, if Consumers want to request specific behavior from Service Providers, they should do so by being explicit in their use of query parameters.



 TOC 

6.2.2.  Sorting

Sorting allows requests to specify the order in which Entries are returned.

sortBy
Specifies the field name whose value SHALL be used to order the returned Entries. The sort order is determine by the sortOrder parameter. If sortBy is a Singular Field, Entries are sorted according to that field's value; if it's a Plural Field, Entries are sorted by the Value (or Major Value, if it's a Complex Field, see Section 7.1 (Basic Structure)) of the field marked with "primary": "true", if any, or else the first value in the list, if any, or else they are sorted last if the given Entry has no metadata for the given field.
sortOrder
The order in which the sortBy parameter is applied. Allowed values are ascending and descending. If a value for sortBy is provided and no sortOrder is specifies, the sortOrder SHALL default to ascending. Sort order is expected to be case-insensitive Unicode alphabetic sort order, with no specific locale implied.



 TOC 

6.2.3.  Pagination

The pagination parameters can be used together to "page through" a large number of results in manageable chunks:

startIndex:
Specifies the offset of the first result to be returned with respect to the list of Entries that would be returned if no startIndex were provided. For instance, if in a given request 10 Entries would normally be provided, if startIndex is 7 and no count is specified, then only the last 3 Entries in that list would be returned (Entries are zero-indexed). If startIndex is greater than or equal to the total number of results that would be returned, no Entries are returned. Value MUST be a non-negative integer and defaults to 0 if no value is specified.
count:
If non-zero, specifies the maximum number of Entries the Consumer would like the Provider to return at a time. Value MUST be a non-negative integer and defaults to 0 if no value is specified. A count of 0 means that is up to the Provider to determine how many Entries to return by default (some Providers may return all Entries by default; others may return a fixed default number like 10). Providers SHOULD honor a very large count value, and SHOULD support returning all Entries at once when presented with a count request that is larger than the number of Entries the user has, but Providers MAY choose to never return more than a Provider-determined maximum number of Entries per request, if returning all Entries is too burdensome. In all cases, at most count Entries SHALL be returned, starting at startIndex and counting up from there. In each of these cases, Providers MUST indicate the total number of Entries they chose to return in the response using the itemsPerPage response element (see Section 6.3 (Response Format)).

For instance, on an initial query, specifying startIndex=0&count=10 will return only the first 10 results. The total number of possible results is indicated by the totalResults field of results, so the client knows how many "pages" of results exist. A subsequent query of startIndex=10&count=10 will return the next 10 results, and so on.



 TOC 

6.2.4.  Presentation

Presentation controls the format, makeup, and delivery mechanism for returning the requested result set:

fields:
If non-empty, each Entry returned SHALL contain only the fields explicitly requested. A Service Provider MAY return a subset of the requested fields if they are not supported. A Provider SHOULD return at least the id and displayName fields for an Entry. This parameter is used for efficiency when a Consumer wishes to access only a subset of the fields. Value is a comma separated list of top level field names (e.g. id,title), and it defaults to an empty list which means it's up to the Provider which fields to return. Consumers MAY request all available fields by using the special value @all_fields (i.e. any field). Providers MUST decline to present results if the specified fields parameter format is not recognized (as per Section 6.2.5 (Declining to honor query parameters)).
links:
If non-empty, each Entry returned SHALL contain only the links explicitly requested. A Service Provider MAY return a subset of the requested links if they are not supported. This parameter is used for efficiency when a Consumer wishes to access only a subset of the links. Value is a comma separated list of link names (e.g. links), and it defaults to an empty list which means it's up to the Provider which links to return. Consumers MAY request all available links to be returned by using the special value @all_links (i.e. any link). Providers MUST return the requested links information using a LINK structure as explained in Section 7.1.2 (Links). Providers MUST decline to present results if the specified links parameter format is not recognized (as per Section 6.2.5 (Declining to honor query parameters)).
relationships:
If non-empty, each Entry returned SHALL contain only the relationship labels explicitly requested. A Service Provider MAY return a subset of the requested relationships if they are not supported. A Provider SHOULD return at least the href and entry fields for relationships included by-reference and by-value respectively (see Section 7.1.3 (Relationships)). This parameter is used for efficiency when a Consumer wishes to access only a subset of the relationships. Value is a comma separated list of top level relationship names (e.g. contributor,creator,crossPromotions), and it defaults to an empty list which means it's up to the Provider which relationships to return. Consumers MAY request all available relationships by using the special value @all_relationships (i.e. any relationship). Providers MUST return the requested relationships information using a Complex Field structure as explained in Section 7.1.3 (Relationships). Additionall a Provider MAY use the includeRelationships parameter (see below). Providers MUST decline to present results if the specified fields parameter format is not recognized (as per Section 6.2.5 (Declining to honor query parameters)).
format:
Specifies the format in which the response content metadata is returned. Service Providers MUST support the values json for JSON (http://json.org) and MAY support additional formats if desired. The format defaults to json if no format is specified. Singular Fields are encoded as string key/value pairs in JSON, e.g. "field": "value". Plural Fields and Plural Bundles are encoded as arrays in JSON, e.g. "fields": [ "value1", "value2" ]. Nodes with multiple sub-nodes are represented as objects in JSON, e.g. "field": { "subfield1": "value1", "subfield2": "value2" }.
includeRelationships:
This is an optional parameter and it MUST be used in combination with the relationships parameter. If non-empty, it MUST specifies a valid boolean value of 'true' or 'false'. If the value is 'true' a Provider SHOULD include relationships information using an inline entry structure as explained in Section 7.1.3 (Relationships) and Section 6.3 (Response Format). A Provider SHOULD expand only the immediate Sub-Entries, one level only. Providers MAY support the expansion of an arbitrary number of levels of Sub-Entries. A Provider SHOULD NOT expand the same Sub-Entry multiple times in the scope of the same Entry (e.g. a Programme Entry which is connected to a Contact Entry multiple times via the contributor relationship as 'director' or 'writer'). For efficiency a Provider MAY NOT expand the same Sub-Entry multiple times in the scope of the same request. A Consumer SHOULD BE able to process at least one level of inclusion of Sub-Entries, and MAY ignore any sub-levels of inclusion if not supported or understood. A Provider SHOULD NOT filter an inline entry structure using the fields parameter as it complicates the processing of the request.
listFields:
This is an optional parameter. If non-empty, it MUST specifies a valid boolean value of 'true' or 'false'. If the value is 'true' a Provider SHOULD list the existing simple and complex field names (Section 7.1.1 (Fields)) in the metadataFields Entry structured field as Entry Metadata. Otherwise no extra field SHALL be included. When used in combination with the fields parameter only field names not listed in the fields parameter SHALL be returned.
listLinks:
This is an optional parameter. If non-empty, it MUST specifies a valid boolean value of 'true' or 'false'. If the value is 'true' a Provider SHOULD list the existing Web link field names (Section 7.1.2 (Links)) in the metadataLinks Entry structured field as Entry Metadata. Otherwise no extra field SHALL be included. When used in combination with the fields parameter only Web link field names not listed in the fields paramters SHALL be returned.
listRelationships:
This is an optional parameter. If non-empty, it MUST specifies a valid boolean value of 'true' or 'false'. If the value is 'true' a Provider SHOULD list the existing relationship field names (Section 7.1.3 (Relationships)) in the metadataRelationships Entry structured field as Entry Metadata. Otherwise no extra field SHALL be included. When used in combination with the fields parameter only relationship field names not listed in the fields paramters SHALL be returned.

For example, assuming the Service Provider has the information as listed in the previous example by issuing this request:

GET /api/listings/5E5EEBED3173?fields=title,alternativeTitle&
                relationships=contributor&
                includeRelationships=true HTTP/1.1
Host: api.example.org

The following Entry would be returned:

HTTP/1.1 200 OK
Content-Length: ...
Content-Language: en
Content-Type: application/listings+json

{
    "entry": {
      "id": "5E5EEBED3173",
      "objectType": "episode",
      "displayName": "Episode 1",
      "title": "Pilot",
      "alternativeTitle": {
        "type": "original",
        "value": "Northwest Passage"
      },
      "contributor": [
        {
          "entry": {
            "id": "C675EDD23A2D",
            "objectType": "person",
            "displayName": "David Lynch",
            "name": {
              "middleName": "Keith"
            },
            "birthday": "1946-01-20"
          },
          "role": "director"
        },
        {
          "entry": {
            "id": "2F050A9AF481",
            "objectType": "person",
            "displayName": "David Lynch"
          }
          "role": "writer"
        },
        {
          "entry": {
            "id": "2F050A9AF481",
            "objectType": "person",
            "displayName": "Mark Frost"
          }
          "role": "writer"
        }
      ]
    }
}

While instead by issuing this request:

GET /api/listings/5E5EEBED3173?fields=title,alternativeTitle&
                relationships=contributor&listRelationships=true
                &listFields=true&listLinks=true HTTP/1.1
Host: api.example.org

The following Entry would be returned:

HTTP/1.1 200 OK
Content-Length: ...
Content-Language: en
Content-Type: application/listings+json

{
    "entry": {
      "id": "5E5EEBED3173",
      "objectType": "episode",
      "displayName": "Episode 1",
      "title": "Pilot",
      "alternativeTitle": {
        "type": "original",
        "value": "Northwest Passage"
      },
      "contributor": [
        {
          "href": "C675EDD23A2D",
          "role": "director",
          "label": "David Lynch",
          "primary": true
        },
        {
          "href": "C675EDD23A2D",
          "role": "writer",
          "label": "David Lynch"
        },
        {
          "href": "2F050A9AF481",
          "role": "writer",
          "label": "Mark Frost"
        }
      ],
      "metadataFields": [
        "summary",
        "position"
      ],
      "metadataLinks": [
        "links",
        "thumbnails"
      ],
      "metadataRelationships": [
        "parent",
        "peers","
        "service",
        "versions"
      ]
    }
}


 TOC 

6.2.5.  Declining to honor query parameters

Providers SHOULD honor all filtering, sorting and pagination values requests specified via Query Parameters. However, in some instances it may be too burdensome to comply with a particular request, e.g. because the Provider does not have an efficient database index set up for a given field that is requested for filtering or sorting, and is unable to efficiently fetch all metadata and post-process the results to honor the request before returning the response. In such cases, Providers MAY decline to honor the request (or specific pieces of the request). If any part of the request is declined, Providers MUST specify which part(s) of the request were declined in the response, using "sorted": false, "filtered": false, "updatedSince": false and/or "updatedUntil": false as appropriate. For efficiency, Providers SHOULD omit these response fields if that part of the request was successfully performed, or if no such Query Parameter was specified in the request.

Note that since all of the filtering, sorting and pagination operations are designed to reduce the amount of metadata returned, it is possible for Consumers to emulate these operations client-side when a Provider declines to perform them server-side. For instance, filtering can be accomplished by iterating through each entry returned and deleting those that do not match the filtering criteria. Thus Consumers can request these operations to be performed server-side, and Providers will honor them if possible, and otherwise indicate to Consumers that they need to be performed client-side, effectively "splitting the workload" while maintaining consistent semantics.



 TOC 

6.3.  Response Format

The structure of the response object returned from a successful request is as follows.

The root element is an anonymous JSON object. The root node MUST contain the following child nodes, and MAY contain additional nodes that the Service Provider wishes to add to expose additional information. Note that startIndex, itemsPerPage, and totalResults are based on [OpenSearch] (Clinton, D., “OpenSearch 1.1,” .). See the Appendix for a full example.



 TOC 

6.4.  Error Codes

The Service Provider MUST return a response code with every response. Response codes are numeric and conform to existing HTTP response codes where possible, as defined below. In addition to the response code, Service Providers SHOULD also provide a human-readable reason that explains the reason for the response code. This message SHOULD be intelligible to developers, but MAY be unsuitable for display to end-users. Clients SHOULD provide their own appropriate error message to users when encountering an error response.

Service Providers SHOULD conform to the following response codes to indicate the following situations. Service Providers MAY return additional codes to indicate additional information, but are discouraged from doing so and should instead augment the reason text with existing codes, if possible.

200:
OK (response returned successfully)
400:
Bad Request (request was malformed or illegal and cannot be completed)
401:
Unauthorized (authentication headers / parameters were invalid or missing)
404:
Not Found (the request points to an object that does not exist, e.g. to an unknown Entry id; note that Service Providers MUST return a 200 with an empty array of Entries if the request has filtering parameters that are valid but have no matches)
500:
Internal Server Error (un unexpected error occurred during processing)
503:
Service Unavailable (service is temporarily unavailable; this may be because the Consumer has exceeded their rate-limit of requests)



 TOC 

6.5.  Authentication and Authorization

The content metadata returned by a Portable Listings endpoint MAY contain public metadata, or it MAY contain private metadata. If the metadata returned is public, no authentication or authorization is required. Often however, the metadata returned is not public, and Service Providers SHOULD ensure that the user or the metadata provider (or user) has given prior consent, either explicitly or implicitly, for their information to be released by this API. Typically this is done by Consumers obtaining either Direct Authorization (with raw credentials, for example the user's username and password) or Delegated Authorization (with an access token obtained out-of-band by the user, and given to the Consumer to present as part of the request). Portable Listings specifies standard mechanisms for both types of authorization, so that Consumers may be able to obtain private metadata on a metadata provider's or user's behalf from Service Providers in an automated and consistent fashion. Regardless of the Authorization method used, the context of the request (i.e. the metadata service or user for whom metadata is being requested) MUST be inferred by Service Providers from the Base URL and the authorization credentials provided. If public data is being accessed (and no authorization is provided), the Base URL MUST contain enough information for Service Providers to know which metadata to return, but if private metadata is being accessed (and authorization is provided), the same Base URL MAY return information for different metadata services or users depending on the authorization credentials provided.



 TOC 

6.5.1.  Delegated Authorization

Service Providers wishing to provide Delegated Authorization MUST support [OAuth 2.0] (, “The OAuth 2.0 Authorization Protocol,” .) as an OAuth Service Provider, and MAY also support additional Delegated Authorization mechanisms, if they choose. Service Providers supporting OAuth SHOULD provide a mechanism for Consumers to automatically obtain an access token, but MAY require this to be done out-of-band.



 TOC 

6.5.2.  Direct Authorization

Service Providers wishing to provide Direct Authorization MUST support HTTP Basic Access Authentication [RFC2617] (Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication,” June 1999.), and MAY also support additional Direct Authorization mechanisms, if they choose. In addition to being a well-established mechanism for Direct Authorization, HTTP Basic has the added benefit of being understood by most Web Browsers, and can prompt users to enter their credentials as part of accessing a resource protected in this manner. There are also convenient ways of providing and parsing HTTP Basic credentials in popular tools and libraries.



 TOC 

6.5.3.  Available Authorization Methods

Service Providers that provide access to private metadata MAY choose not to support either Direct Authorization or Delegated Authorization, depending on their security requirements, but they MUST support either OAuth or HTTP Basic auth if they require any Authorization. When accessing a Portable Listings endpoint, if sufficient authorization credentials are not provided, the Service Provider SHOULD return a 401 Unauthorized response, and SHOULD provide the available Authorization mechanisms available by including WWW-Authenticate headers in the response for each type of Authorization method supported (as defined in [RFC2616] (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.), section 14.47). Consumers will then be able to recognize that the API is a protected resource and initiate the proper Authorization process needed to obtain the appropriate credentials. An example set of WWW-Authenticate headers returned by a Service Provider that supports both OAuth and HTTP Basic might look like this. Note that the realm value is intended to be an opaque string that merely defines a shared label for resources that share the same authorization requirements.

WWW-Authenticate: OAuth realm="sample.site.org"
WWW-Authenticate: Basic realm="sample.site.org"

If Service Providers wish to make some response metadata publicly available and also provide additional info given the proper authorization credentials, they SHOULD provide a 200 OK response to requests without authorization with a WWW-Authenticate header in the response indicating that additional info is available via the specified authorization mechanisms.



 TOC 

7.  Listings Format

The Portable Listings format is expressed in terms of profiles identified with a URI per [RFC6906] (Wilde, E., “The 'profile' Link Relation Type,” March 2013.).

In the scope of this specification a profile is defined using the basic structures defined in Section 7.1 (Basic Structure). In addition a profile MAY also define addition constraints and guidelines for a Consumer application.

An Entry is defined to be "compliant" with a profile if and only if it adheres to the format structures, the contraints and the requirements set in a profile description. A Entry MAY be compliant with multiple profiles.

Unless specifically forbidden by a particular profile definition, an Entry can contain arbitrary fields and relationships. Consumer MAY choose to ignore any unknown information and continue processing.

This specification defines the core profile and it is the only profile that a Portable Listings implementation is required to support (see Section 8 (Core Profile)). Support for other profiles is optional. If a Consumer is presented with an Entry expressed using an unknown profile, the Consumer MAY choose to ignore it and continue processing.



 TOC 

7.1.  Basic Structure

Each Entry is defined as a set of fields, links and relationships. Each Entry MUST have a unique identifier and an object type. The order in which Entry fields, links and relationships are defined is not significant. By definition an Entry has object type of entry. Objects are represented in a result set with the entry element (see Section 6.3 (Response Format)) and the object type is specified using lowercased object type name as value of the objectType field. Unless specified otherwise and as general rule, all fields, links and relationships applying to a specific Entry type SHALL BE applicable to any Entry sub-type (e.g. fields and relationships defined for programme apply to series).



 TOC 

7.1.1.  Fields

Each field is defined as either a Singular Field, in which case there MUST NOT be more than one instance of that field per Entry, or as a Plural Field, in which case any number of instances of that field MAY be present per Entry. By definition, each Entry returned to a Consumer MUST include the id and displayName fields with non-empty or no null values, but all other fields are optional.

Entry fields information is formatted using labeled attributes with either structured or unstructured values. Each attribute value consists of one of the following types:

Simple:
A single value attribute. Unless otherwise specified, a Simple field is by definition a STRING. A Simple Field value can be any of the following datatypes:
STRING:
A string value as defined in section 2.5 in [RFC4627] (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.). A string attribute MAY be used to specify a REQUIRED data type format (e.g. URI, DATE) or allow any string.
NUMBER
An interger or floating point numeric value as defined in section 2.4 in [RFC4627] (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.).
BOOLEAN:
A boolean value as defined in section 2.1 in [RFC4627] (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.). Values are case-sensitive.
NULL:
An null value as defined in section 2.1 in [RFC4627] (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.). The value is case-sensitive. A field with value null is considered to be the same as if the field value was omitted. This value is a valid value for any field which is not specified as REQUIRED.
HTML:
The special value type HTML is used to describe a STRING which contains a string of characters that would be valid if used within a DIV container element in an HTML document, as defined by [HTML5] (W3C, “HTML5 - A vocabulary and associated APIs for HTML and XHTML,” .). Since strings as defined in section 2.5 in [RFC4627] (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.) are strings of unicode characters rather than octets, care may be required in some implementations to ensure that the default character encoding of an HTML parser used to parse the content of such a string is correctly configured to match the encoding of the string in that implementation's internal string representation.
IRI:
The special value type IRI is used to describe a string which contains an IRI as defined in [RFC3987] (Duerst, M. and M. Suignard, “Internationalized Resource Identifiers (IRIs),” January 2005.). Note that the definition of "IRI" excludes relative references. Though the IRI might use a dereferencable scheme, Consumers MUST NOT assume it can be dereferenced. Because of the risk of confusion between IRIs that would be equivalent if they were mapped to URIs and dereferenced, the following normalization strategy SHOULD be applied when generating values for fields of type IRI:
  • Provide the scheme in lowercase characters.
  • Provide the host, if any, in lowercase characters.
  • Only perform percent-encoding where it is essential.
  • Use uppercase A through F characters when percent-encoding.
  • Prevent dot-segments from appearing in paths.
  • For schemes that define a default authority, use an empty authority if the default is desired.
  • For schemes that define an empty path to be equivalent to a path of "/", use "/".
  • For schemes that define a port, use an empty port if the default is desired.
  • Preserve empty fragment identifiers and queries.
  • Ensure that all components of the IRI are appropriately character normalized, e.g., by using NFC or NFKC.
LANGUAGE:
The special value type LANGUAGE is used to describe a valid language code value as defined in [RFC5646] (Phillips, A. and M. Davis, “Tags for Identifying Languages,” September 2009.).
TIMESTAMP:
The special value type TIMESTAMP is used to describe a string which contains a valid timestamp as defined in [RFC3339] (Klyne, G., Ed. and C. Newman, “Date and Time on the Internet: Timestamps,” July 2002.).
TIME:
The special value type TIME is used to describe a string which represents an instant of time that recurs every day as defined in section 3.2.8 of [XSD‑DATATYPES] (Biron, P. and A. Malhotra, “XML Schema Part 2: Datatypes Second Edition,” October 2004.).
YEAR:
The special value type YEAR is used to describe a string which represents a gregorian calendar year as defined in section 3.2.11 of [XSD‑DATATYPES] (Biron, P. and A. Malhotra, “XML Schema Part 2: Datatypes Second Edition,” October 2004.).
DURATION:
The special value type DURATION is used to describe a string which represents a duration of time as defined in section 3.2.6 of [XSD‑DATATYPES] (Biron, P. and A. Malhotra, “XML Schema Part 2: Datatypes Second Edition,” October 2004.) and ISO 8601 [ISO8601‑duration] (ISO, “ISO 8601,” .).
TIMECODE:
The special value type TIMECODE is used to describe a string which represents a duration expressed in timecode using the ANSI/SMPTE 12M-1986 (Timecode) format [ANSI‑SMPTE‑12M‑1986] (SMPTE, “SMPTE time code,” .).
PERIOD:
The special value type PERIOD is used to describe a string which represents a time interval as defined in [DCMI‑PERIOD] (, “DCMI Period Encoding Scheme,” .).
TERRITORY:
The special value type TERRITORY is used to describe a string which represents a country or territory as defined in ISO 3166 [ISO3166] (ISO, “ISO 3166,” .).
PLACE:
The special value type PLACE is used to describe a string which represents a geographical Point as defined in GeoJSON [GEO‑JSON] (, “The GeoJSON Format Specification,” .).
ENUM:
A simple field MAY contain Canonical Values specified as an enumerated list of valids to represent specific Reference Data values (see for example the core profile Section 8.1 (Reference Data)). In this case Service Providers SHOULD try to conform to those values if appropriate, but MAY provide alternate values to represent additional values.
Providers MAY support additional Simple field string type values if they choose. Consumer MAY choose to ignore any unknown information or process those values as STRING.

Complex:
A multi-value attribute containing any combination of other attributes. Complex attributes are defined by listing the child attributes and their types. For most Complex Fields, the value sub-field contains the Major Value of that field (i.e. the primary piece of listings information described by that field) and the other fields provide additional information about the field itself. A Complex Field is marked with the COMPLEX keyword in the rest of this document.

Unless specified otherwise, and except for the structures defined in Section 7.1.2 (Links) and Section 7.1.3 (Relationships), all Plural Complex Fields (i.e. plural fields which instances are not a simple value) have the same four standard sub-fields:
value: (SIMPLE)
The primary value of this field, e.g. an alternative title, URL or e-mail address. When specifying a sortBy field in the Query Parameters for a Plural Field, the default meaning is to sort based on this value sub-field. Each non-empty Plural Field value MUST contain at least the value sub-field, but all other sub-fields are optional.
primary: (BOOLEAN)
A Boolean value indicating whether this instance of the Plural Field is the primary or preferred value of for this field, e.g. the preferred mailing address or primary e-mail address. Service Providers MUST NOT mark more than one instance of the same Plural Field as primary="true", and MAY choose not to mark any fields as primary, if this information is not available. For efficiency, Service Providers SHOULD NOT mark all non-primary fields with primary="false", but should instead omit this sub-field for all non-primary instances.
type: (ENUM)
The type of field for this instance, usually used to identify the preferred function of the given listings information. This string generally is specified to contain a valid Canonical Value picked from a pre-defined list. For example in an alternativeTitle the type sub-field string value could be original or working (see Section 8.1 (Reference Data)).
label: (STRING)
A human-readable label or name associated to the value sub-field.
lang: (LANGUAGE)
The language of the attribute value. The value MUST be a valid LANGUAGE Canonical Value.
attributionDate: (TIMESTAMP)
The date at which the specific attribute vaue was attributed.
note: (STRING or HTML)
A note on the attribute value to provide additional contextual information.
Also unless specified otherwise, when returning Plural Fields, Service Providers SHOULD canonicalize the value returned, if appropriate (e.g. for URLs and e-mail addresses). Providers MAY return the same value more than once with different types , but SHOULD NOT return the same (type, value) combination more than once per Plural Field, as this complicates processing by the Consumer.

In the rest of this document, a required field (or sub-field) is marked with the REQUIRED keyword.

A Simple Field is marked with the SIMPLE keyword or the uppercase identifier of its datatype (e.g. STRING, DATE). A Complex Field is marked with the COMPLEX keyword or the uppercase identifier of its complex datatype (e.g. LINK, SOURCE). Some fields MAY be defined as accepting multiple datatypes using the "or" combinator. For example, the type "STRING or NUMBER" indicates that a Simple Field may accept either a string or a numeric value.

Field structures will be described as follow:

singularField: (DATATYPE)
A Singular Field with a SIMPLE or COMPLEX value with datatype DATATYPE.
pluralField: [DATATYPE]
A Plural Field with an Array of SIMPLE of COMPLEX values with datatype DATATYPE.



 TOC 

7.1.2.  Links

A multi-value attribute which represent a standard LINK as defined by section 3 of [RFC5988] (Nottingham, M., “Web Linking,” October 2010.). This enables Providers to create generic standard links between an Entry and other resources, including other Entries (see Section 7.1.3 (Relationships)), using the registry of links relations defined by the Web Linking specification and HTML5 Link types [HTML5] (W3C, “HTML5 - A vocabulary and associated APIs for HTML and XHTML,” .). The Context of the LINK is the Entry which has a field using the LINK construct as value.

href: (IRI)
REQUIRED. The IRI of the link. This IRI MAY be relative or absolute. If the URI is relative it is resolved against the Service Provider root API endpoint URL. Unless otherwise specified, this is the Primary Sub-Field for the field having this construct as value, for the purposes of sorting and filtering. The value and lang sub-fields SHALL not be specified.
rel: (ENUM or IRI)
The link relation type. Unless otherwise specified, the rel value MUST be a valid Canonical Value as defined in [IANA‑RELREG] (IANA, “Link Relation Types,” .) and in Section 8.3 (Additional Link Relation Types). If this property is omitted or null it MUST BE processed as if the value was the string "alternate".
type: (ENUM)
The media type of the representation identified by the IRI of the link. The value is a hint about the type of the representation that is expected to be returned when the value of the href field is dereferenced. Note that the type field does not override the actual media type returned with the representation. A link construct MAY have a type sub-field, whose value MUST conform to the syntax of a MIME media type defined in [MIMEREG] (Freed, N. and J. Klensin, “Media Type Specifications and Registration Procedures,” December 2005.). Unless otherwise specified, the type value field MUST be a valid Canonical Value as defined by the IANA MIME Media Types registry [IANA‑MIMEREG] (IANA, “MIME Media Types,” .).
hreflang: (LANGUAGE)
The content language of the representation identified by the IRI of the link. When used together with the rel sub-field with value "alternate", it implies a translated version of the Context of the link. A link construct MAY have an hreflang sub-field, whose value MUST be a valid LANGUAGE Canonical Value.
label: (STRING)
A human-readable label about the link.
length: (NUMBER)
The content length in octets of the representation identified by the IRI of the link. The value is a hint about the content length of the representation returned when the IRI in the href sub-field is mapped to a URI and dereferenced. Note that the length sub-field does not override the actual content length of the representation as reported by the underlying protocol.
width: (NUMBER)
When the target resource is a visual media item, for example if the media type is image/* or video/*, this value is a hint about the item's intrinsic or ideal width in pixels.
height: (NUMBER)
When the target resource is a visual media item, for example if the media type is image/* or video/*, this value is a hint about the item's intrinsic or ideal height in pixels.
duration: (NUMBER)
When the target resource is a time-based media item, for example if the media type is video/* or audio/*, this value is a hint about the item's approximate duration in seconds.

Unless otherwise specified, when the link construct is used in a Plural Field, Providers MAY return the link construct with the same href and rel values combination more than once with different type, hreflang, label, length, width, height or duration, but MUST NOT return more than once the same type and hreflang combination for a given href with rel field of value "alternate".



 TOC 

7.1.3.  Relationships

A relationship expresses a directed labeled and typed connection from a Source Entry (or relationship Context Entry) to a Target Entry. Each relationship MUST have a label and a type. Each relationship between two Entries is defined as either a Singular Relationship, in which case there MUST be one and only one Sub-Entry associated, or as a Plural Relationship, in which case any number of Sub-Entries MAY be associated to the source Entry being described. When a relationship is defined as REQUIRED its minimal cardinality is set to one Sub-Entry. A Provider MAY express multiple relationships between two given Entries, either with the same or different labels and types. For example, a Programme Entry could be connected to a Person Entry either via the creator, publisher or contributor relationship. The Core profile (see Section 8 (Core Profile)) defines a pre-defined set of relationship names, based on existing industrial standards and vocabularies aiming to provide a standard list of named relationships.

Entry relationships information is formatted using a multi-value attribute for a Singular Relationship, and a multi-value attribute listing the child attributes for a Plural Relationship. The field name is defined to be the relationship label (e.g. creator, publisher or contributor). The relationship multi-value attribute MUST BE a direct child of the entry element representing the Source Entry (i.e. a sub-field can not be used to express a relationship). A relationship multi-value attribute MAY have additional sub-fields, but MUST NOT contain multi-value attributes representing other relationships.

The structure of the multi-value attribute varies depending whether the relationship information is requested by-reference or by-value as follow:

by-reference
The relationship is formatted using a LINK structure as defined in Section 7.1.2 (Links) with the following differences:
href: (IRI)
REQUIRED. The value MUST BE a valid URL reference to a Service Provider Portable Listings API endpoint including path information and other query parameters which can be used to request a single Target Entry connected with the Source Entry via the named relationship (see Section 6.1 (Requesting Specific Information)). Note that this definition also covers the scenario of relationships expressed between Entries across Service Providers. Although a Provider SHOULD NOT reference Entries on another Provider as this complicates processing by the Consumer.
type: (ENUM)
If non-empty or null, the media type is defined to be application/listings+json. The profile media type parameter MAY be specified as defined in Section 7.4 (Referencing Profiles).
rel: (ENUM or IRI)
The value must be a valid relation type as defined in [IANA‑RELREG] (IANA, “Link Relation Types,” .) and in Section 8.3 (Additional Link Relation Types). If this attribute is omitted it MUST BE processed as if the value were the string "related".
hreflang: (LANGUAGE)
The content language of the metadata Entry referenced. The value MUST be a valid LANGUAGE Canonical Value.
label: (STRING)
If non-empty or null, the label SHOULD match the displayName field of the Sub-Entry.
A Provider MAY define additional fields if necessary.
by-value
The relationship is formatted using an "inline entry" multi-value attribute defined as follows:
entry:
REQUIRED. It MUST contain the exact content of the entry element representing the Target Entry structure connected with the Source Entry via the named relationship.
rel: (ENUM or IRI)
The link relation type. The value must be a valid relation type as defined in [IANA‑RELREG] (IANA, “Link Relation Types,” .) and in Section 8.3 (Additional Link Relation Types). If this attribute is omitted it MUST BE processed as if the value were the string "related".
lang: (LANGUAGE)
The content language of the metadata Entry included. The value MUST be a valid LANGUAGE Canonical Value.
label: (STRING)
The label SHOULD match the displayName field of the Sub-Entry.
A Provider MAY define additional fields if necessary.

Note that the above definitions effectively require a Provider to represent each individual member of a relationship using one multi-value attribute for each individual associated Sub-Entry.

For efficiency, Service Providers SHOULD return relationships information by-reference. A Consumer MAY explicitly request to include relationships information by-value as explained in Section 6.2.4 (Presentation).

Again for efficiency, Service Providers MAY return only a sub-set of all the connected Sub-Entries inside a Source Entry. A Consumer MUST BE able to retrieve the complete list of Sub-Entries wrapped into one single entry element (single object or array) using additional path information (e.g. http://api.example.org/api/listings/5E5EEBED3173/contributor - see Section 6.1 (Requesting Specific Information)).

In the rest of this document, a required relationship is marked with the REQUIRED keyword. A relationship (either to be included by-reference or by-value) is marked with the RELATIONSHIP keyword or with the uppercase identifier of the object type of the Target Entry (e.g. PERSON, ENTRY, PROGRAMME etc). Some relationships may be defined as accepting multiple object types using the "or" combinator. For example, the type "GROUP or ORGANISATION" indicates that a relationship may accept as Target Entry a Group or an Organisation.

Relationships structures will be described as follow:

singularRelationshipLabel: (OBJECTYPE)
A Singular Relationship with a lablel of singular_relationship_label connecting the Source Entry containing the named relationship attriubute with a Target Entry of type OBJECTYPE. The relationship type is expressed using the rel sub-field.
pluralRelationshipLabel: [OBJECTYPE]
A Plural Relationship with a lablel of plural_relationship_label connecting the Source Entry containing the named relationship attriubute with a Target Entry of type OBJECTYPE. The relationship type is expressed using the rel sub-field.



 TOC 

7.2.  Multilingual Fields

The Content-Language HTTP header SHOUDL BE used by a Service Provider to signal a Consumer that the fields returned are expressed in a specific language. If the language is not specified, the fields language is left undefined.

A Provider MAY return fields in multiple languages using the MIME multipart/alternative Content-Type in combination with the Content-Language header (see section 4.2 in [RFC5646] (Phillips, A. and M. Davis, “Tags for Identifying Languages,” September 2009.)).

A Consumer MAY request metadata in one or more languages using the HTTP Accept-Language header.



 TOC 

7.3.  Interoperability Considerations

Interoperability between Portable Listings implementations relies on the ability to for those implementations to rely on a consistent collection of required metadata elements. The core profile described in Section 8 (Core Profile) is intended to provide a foundation upon which such interoperability MAY be based. New profiles MAY choose to either extend or modify the requirements specified by the core. Profiles that seek only to extend the core without changing any of those core requirements will have a much greater chance of ensuring appropriate levels of interoperability. Profiles that modify the core requirements run the risk of breaking interoperability in Portable Listings implementations. Because of this, for the sake of protecting interoperability, it is highly recommended that new profiles seek to extend the core rather than modify it.



 TOC 

7.4.  Referencing Profiles

A Service Provider SHOULD signal a Consumer that the Entries are expssed using specific profiles by returning the Content-Type HTTP header with the media type parameter profile containing a whitespace-separated list of the profile URIs used.

Alternatively profiles MAY be referenced per [RFC6906] (Wilde, E., “The 'profile' Link Relation Type,” March 2013.) as follow:

A Provider SHOULD return a profile identifier with each Consumer request. The core profile is the default profile for all Entries returned by a Service Provider unless otherwise specified. Consumer SHOULD ignore any Entry object types, fields or relationship they do not understand. Note that the profile Content-type parament and field are intended only as a hint. A Consumer application MAY use it to help make decisions about an Entry but the presence of a particular profile identifier in the media type does not place any obligations on the application.



 TOC 

8.  Core Profile

The core profile aims to provide a minimal metadata set to identify and describe a piece of audiovisual content through the whole content value chain. It is expected that other specifications will be produced that to define formats specific to various broadcasting and audiovisual applications.

Where possible the structure and semantics were directly taken directly from industry and open standards such as [EBUCORE] (EBU, “EBU – TECH 3293 - EBU Core Metadata Set (EBU Core) v.1.4,” .), [EBU‑OBJECTMODEL] (EBU, “EBU Object Model,” .), [TV‑ANYTIME] (ETSI, “TV Anytime,” .) and [BBC‑PROGRAMMES] (BBC, “Programmes ontology,” .), trying also to align as much as possible with existing work done with [PortableContacts] (Smarr, J., “Portable Contacts 1.0 Draft C,” .), [MEDIA‑RSS] (Yahoo! Inc. and RSS Advisory Board, “Media RSS Specification,” .), [ATOM‑MEDIA] (Atkins, M., “Atom Media Extensions,” .), [HTML5] (W3C, “HTML5 - A vocabulary and associated APIs for HTML and XHTML,” .) Video and Media Multitrack definitions [HTML5‑MM] (W3C, “Media Multitrack API,” .) and related specifications.

The following guidelines were followed to transform the input standard scheme into the core profile:



 TOC 

8.1.  Reference Data

Well-defined Canonical Values MAY BE used for string-valued fields as reference data. For example, a Canonical Value can be used to express the type sub-field in a Complex Field. Where possible and useful the Reference Data and Canonical Values SHOULD BE selected from a standard list of values such as the EBU Metadata Reference Data and Classification Schemes [EBU‑REFERENCEDATA] (EBU, “European Broadcasting Union - Metadata Reference Data,” .) or the TV-Anytime Classification Schemes [TV‑ANYTIME] (ETSI, “TV Anytime,” .). A Provider MAY either use the well-defined and standardised lists of Canonical Values or it MAY define application specific values which a Consumer can reference.



 TOC 

8.2.  Profile Identifier

The core profile is identified with the URI http://portablelistings.net/profiles/core/1.0/ and it is a reserved string.



 TOC 

8.3.  Additional Link Relation Types

This specification defines a number of additional link relation types that can used to further describe audiovisual content as defined in the EBU Metadata Reference Data and Classification Schemes [EBU‑REFERENCEDATA] (EBU, “European Broadcasting Union - Metadata Reference Data,” .).



 TOC 

8.3.1.  "promotional-information"

The "promotional-information" link relation can be used to refer to something devised to publicize or advertise a resource or associated product about the link's context.

Multiple products can be indicated through the use of multiple "promotional-information" link relations.



 TOC 

8.3.2.  "review"

The "review" link relation can be used to refer to a critical article or report concerning the link's context, e.g. a critique or an evaluation.

Multiple reviews can be indicated through the use of multiple "review" link relations.



 TOC 

8.3.3.  "highlights"

The "highlights" link relation can be used to refer to a resource that represents striking, noticeable aspects of the link's context.

Multiple highlights can be indicated through the use of multiple "highlights" link relations.



 TOC 

8.3.4.  "screenplay"

The "screenplay" link relation can be used to refer to a resource that represents the text specifying content of a production or performance, used as a guide to the link's context. A screenplay MAY include character and setting profiles, production directives (audio, lighting, scenery, camera moves), as well as dialogue to be recited by talent.

Multiple screenplays can be indicated through the use of multiple "screenplay" link relations.



 TOC 

8.3.5.  "transcript"

The "transcript" link relation can be used to refer to an exact copy or reproduction (e.g. of a dialog or interview) of the link's context.

Multiple transcripts can be indicated through the use of multiple "transcript" link relations.



 TOC 

8.3.6.  "shot-list"

The "shot-list" link relation can be used to refer to a resource that represents freeform textual listing of shots, for example indexed against time or frame count.

Multiple shot lists can be indicated through the use of multiple "shot-list" link relations.



 TOC 

8.3.7.  "edit-decision-list"

The "edit-decision-list" link relation can be used to refer to a resource that represents an Edit Decision List (EDL) expressed as handwritten or computer-generated compilation of all edits (marked by their time code in points and out points) to be executed in a video production.

Multiple edit decision lists can be indicated through the use of multiple "edit-decision-list" link relations.



 TOC 

8.3.8.  "rundown"

The "rundown" link relation can be used to refer to a resource that represents a rundown. A rundown sheet is a simple review of the script for the with directions for the various crew members. It can also be breaking the show into "blocks" split by commercial breaks and it lists all the different pieces of the show and what should happen during these pieces (e.g. a graphic will display, or a video tape will be played). This is useful for the crew so that they do not have to read through an entire script during production, they have the show in a simplified form. A rundown can be used for playout.

Multiple rundown can be indicated through the use of multiple "rundown" link relations.



 TOC 

8.3.9.  "dopesheet"

The "dopesheet" link relation can be used to refer to a resource that represents an exposure sheet which allows an animator to organize his thinking and give instructions to the cameraman on how the animation is to be shot.

Multiple expoure sheets can be indicated through the use of multiple "dopesheet" link relations.



 TOC 

8.4.  Object Types

The following sections describe the object structure that can be used to represent a piece of audiovisual content metadata and any related piece of information. Each object is provided with a general description and definitions of its Singular and Plural fields as well as any Singular and Plural Relationships. Any additional requirement or restriction on the object, fields, values and relationships is also outlined. The object types defined within this profile are referenced in CAPITAL letters in the next sections (e.g. PROGRAMME_GROUP). While the actual object type specified in the objectType field MUST BE expressed in lowercase and multiple words have been separated by '_' (underscore) (e.g. ProgrammeGroup became programme_group).

The following object types hierarchy has been defined as integral part of the core profile:

Entry (Entry)

Category (Category)

Content (Content)

Programme (Programme)

Programme Group (Programme Group)

Brand (Brand)

Series (Series)

Programme Item (Programme Item)

Episode (Episode)

Clip (Clip)

Version (Version)

Service (Service)

Programme Publication (Programme Publication)

Broadcast (Broadcast)

Ondemand (Ondemand)

Schedule (Schedule)

Catalogue (Catalogue)

Application (Application)

Application Build (Application Build)

Application Publication (Application Publication)

Application Gallery (Application Gallery)

Media Resource (Media Resource)

Media Group (Media Group)

Segment (Segment)

Segment Group (Segment Group)

Content Collection (Content Collection)

Rights (Rights)

Award (Award)

Agent (Agent)

Person (Person)

Organisation (Organisation)

Group (Group)



 TOC 

8.4.1.  Entry

Entry it is the atomic object type of this specification and it is at the top of the object hierarchy and it is container of a set of common fields and relationships applicable to other object types further defined. The fields list below is broad so that, for Service Providers that do support any of these fields, there is a standard field name or relationship available. It is recognised that not all Service Providers will be able to provide information for all supported fields.



 TOC 

8.4.1.1.  Fields

id: (STRING)
REQUIRED. Unique identifier for the Entry record. Each Entry returned MUST include a non-empty id value. This identifier MUST be unique across the user's entire metadata set (see Section 6.5 (Authentication and Authorization)), but MAY not be unique across multiple users' metadata sets. It MUST be a stable ID that does not change when the same Entry is returned in subsequent requests. Usually, an internal database ID will be the right choice here, e.g. "12345".
displayName: (STRING)
REQUIRED. The short name of this Entry, suitable for display to end-users (e.g. short title). Each Entry returned MUST include a non-empty displayName value. The value provided SHOULD be the primary textual field by which the Entry is normally displayed by the Service Provider when presenting it to end-users. Unless otherwise specified, the displayName value is used for the purposes of sorting and filtering.
objectType: (ENUM)
The object type of the Entry record. A profile defines the possible allowed Canonical Values for the objectType field (see Section 7 (Listings Format)). Different Entries requested by a Consumer can have a different object type. This specification reserves the entry value for referring to object types of Entry, and by definition an Entry without a objectType field or with a objectType value equal to null it is assumed to be of object type Entry. The list of valid Canonical Values for this field consists of the list of lowercased object type names defined in Section 8.4 (Object Types).
published: (TIMESTAMP)
The date the metadata Entry record was first added to the user's metadata set or database (i.e. the creation date of the Entry). This field MAY also be associated with the first availability of the Entry. The value MUST be a valid TIMESTAMP (e.g. 2008-01-23T04:56:22Z).
updated: (TIMESTAMP)
The most recent date the details of the Entry record were updated (i.e. the modified date of the Entry). The value MUST be a valid TIMESTAMP (e.g. 2008-01-23T04:56:22Z). If the Entry has never been modified since its initial creation, the value MUST be the same as the value of updated. Note the updatedSince and the updatedUntil Query Parameters described in Section 6.2 (Query Parameters) can be used to select only Entries whose updated value is equal to or more recent than a given TIMESTAMP or equal to or older than a given TIMESTAMP respectively. This enables Consumers to repeatedly access a metadata Entry and only request newly added or updated Entries since the last access time.



 TOC 

8.4.1.2.  Links

metadataRights: (LINK)
The copyright license terms under which the Entry content metadata is provided. If the field is set, the rel sub-field MUST have the license value.
metadataSource: (LINK)
A standard source from which the Entry metadata record was generated from as defined by section 4.2.11 of [RFC4287] (Nottingham, M., Ed. and R. Sayre, Ed., “The Atom Syndication Format,” December 2005.) using the least minimum number of fields. This enables Providers to simply represent aggregation of Entries. The source field is expressed using the LINK construct with the following differences:
href: (IRI)
REQUIRED. The IRI of the source MUST BE a valid Initial Identifier suitable for discovery of the source Portable Listings API Provider endpoint from where the metadata Entry was derived from as explained in Section 5 (Discovery).
rel: (ENUM)
The rel value MUST BE the "via" relation type as defined in section 6.2.2. of [RFC5988] (Nottingham, M., “Web Linking,” October 2010.). If this property is omitted or null it MUST BE processed as if the value was the string "via".
updated: (TIMESTAMP)
If available, the most recent date the details of the source was updated (i.e. the modified date of the source). The value MUST be a valid TIMESTAMP (e.g. 2010-01-12T07:56:22Z).
links: [LINK]
An Entry MAY have associated one ore more links to external Web resources. A Provider SHOULD NOT use the links element to express relationships by-reference as this complicates processing by the Consumer.



 TOC 

8.4.1.3.  Relationships

metadataPublisher: (AGENT)
The Agent publishing the metadata instances as served by a Service Provider. If the field is set, the rel sub-field MUST have the author value.
parent: (ENTRY)
Relates a piece of content to another piece of content constituting it. This relationship SHOULD BE used to access the parent Entries in Collections, Programme Groups, Series and so on. The following fields are refined for the parent relationship:
rel: (ENUM)
The rel value MUST BE the "up" relation type as defined in section 6.2.2. of [RFC5988] (Nottingham, M., “Web Linking,” October 2010.). If this property is omitted or null it MUST BE processed as if the value was the string "up".
peers: [ENTRY]
Relates a piece of content to other pieces of content which are peers within collection (predecessor/successor). This relationship SHOULD BE used to access the previous and next Entries in Collections, Programme Groups, Series, Episodes (e.g. previous episode, next episode). The following fields are refined for the parent relationship:
rel: (ENUM)
REQUIRED. The rel value MUST BE the "prev" relation type as defined in section 6.2.2. of [RFC5988] (Nottingham, M., “Web Linking,” October 2010.) when referring to a previous Entry in a list or collection. The rel value MUST BE the "next" relation type as defined in section 6.2.2. of [RFC5988] (Nottingham, M., “Web Linking,” October 2010.) when referring to a next Entry in a list or collection.



 TOC 

8.4.2.  Category

The Category object type extends the basic type ENTRY and it represents a user-facing category.



 TOC 

8.4.2.1.  Fields

term: (ENUM OR IRI)
A link or code to or within a classification scheme. The value SHOULD BE selected from a standard list of values.
scheme: (IRI)
An optional fully qualified IRI of the term scheme.
adult: (BOOLEAN)
A flag to indicate contents of this category contain adult material.



 TOC 

8.4.2.2.  Relationships

subCategories: [CATEGORY]
The list of sub-categories. Categories MAY be grouped hierarchically.
rel: (ENUM)
REQUIRED. The rel value MUST BE the "item" relation type as defined in [RFC6573] (Amundsen, M., “The Item and Collection Link Relations,” April 2012.) when referring to a Category part of a hierarchical collection of categories. The rel value MUST BE the "collection" relation type as defined in [RFC6573] (Amundsen, M., “The Item and Collection Link Relations,” April 2012.) when referring to a Category representing a hierarchical collection categories.



 TOC 

8.4.3.  Content

The Content object type extends the basic type ENTRY and it represents an individual piece of audiovisual content metadata returned by a Service Provider. For example, the content object type MAY be used to describe an abstract programme idea or concept created during the planning process, a generic editorial object such as a dope sheet, a script, a report etc. More in general the type MAY be used to describe any other object which is not explicitly contemplated in the core profile (e.g. lenses, camera etc.).



 TOC 

8.4.3.1.  Fields

title: (STRING or HTML)
The main name of this piece of content. The title value provided SHALL differ from the displayName.
alternativeTitle: [COMPLEX]
An alternative name of the piece of content other than the information provided with the displayName, title and subtitle fields.
type: (ENUM)
The type of field SHOULD BE selected from the following list: secondary, subtitle, alternativeSecondary, original, artWorkOriginal, pledged, version, working, alternativeWorking, long, full, abridged, transmission, published, international, translation, pseudo, ingest. The short and main values SHOULD NOT be used as this complicates processing by the Consumer.
value: (STRING or HTML)
The alternative name text.
synopsis: (STRING or HTML)
A brief or condensed statement giving a general view about the piece of content e.g. a brief summary of the plot of a novel, motion picture, play, etc. This is being referred as short synopsis.
description: [COMPLEX]
An extended textual description of the piece of content other than the information provided with the synopsis field. The extended description MAY also consist of outlines, lists, bullet points, edit decision lists, indexes and have references to external media and graphical material.
type: (ENUM)
The type of field SHOULD BE selected from the following list: mediumSynopsis, longSynopsis, summary, annotation, annotationSynopsis, abstract, anecdotalCommentsAndReflections, theme, purpose, outline, cueWords, cueInWords, cueOutWords, process, assessment, editoralComments, keyPoints, shotDescription, creditLine, instructions, modelInformation, artwork, event, releaseInformation, intention, shotComment, citation. The synopsis value SHOULD NOT be used as this complicates processing by the Consumer.
value: (STRING or HTML)
The extended description text.
created: (TIMESTAMP or PERIOD)
The creation date for a particular version or rendition of the piece of content across its life cycle.
issued: (TIMESTAMP or PERIOD)
The date of formal issuance (e.g. publication) of the piece of content.
modified: (TIMESTAMP or PERIOD)
The date when the piece of content was last modified.
digitised: (TIMESTAMP or PERIOD)
The date when the piece of content was digitised.
released: (TIMESTAMP or PERIOD)
The date when the piece of content was released.
copyrighted: (TIMESTAMP or PERIOD)
The date when the piece of content was copyrighted.
productionDate: (YEAR or TIME)
The date when the piece of content was produced. The year SHALL be specified; month and day number MAY optionally be provided additionally. A time point SHALL NOT be specified.
alternativeDate: [COMPLEX]
An alternative date of the piece of content.
type: (ENUM)
The type of field SHOULD BE selected from a standard list of values (e.g. 'accepted', 'submitted'). The created, issued, modified, digitised, released, copyrighted and production values SHOULD NOT be used as this complicates processing by the Consumer. Note that value updated and published values when specified will always refer to the actual piece of content rather than the Entry metadata (see Section 8.4.1 (Entry)).
value: (TIMESTAMP or PERIOD)
The alternative date.
aliases: [COMPLEX]
Additional or alternative identifiers for the piece of content.
value: (IRI or STRING)
The alternative identifier.
authority: (IRI)
An optional issuing authority fully qualified IRI.
tags: [STRING]
A user-defined category or label for the piece of content, e.g. "coolshow" or "web20". These values SHOULD be case-insensitive, and there SHOULD NOT be multiple tags provided for a given Entry that differ only in case. Note that this field is a Plural Simple Field, meaning each instance consists only of a string value.
keywords: [STRING]
A list of keywords and phrases assigned by the Provider to the piece of content, e.g. "sports" or "live". These values SHOULD be case-insensitive, and there SHOULD NOT be multiple keywords provided for a given Entry that differ only in case. Note that this field is a Plural Simple Field, meaning each instance consists only of a string value.
genre: [COMPLEX]
The genre categorising the piece of content other than category and keywords.
value: (ENUM or IRI)
The value SHOULD BE selected from a standard list of values such as the EBU Content Genre, Intention or the TV-Anytime Content Commercial or Content Alert types.
targetAudience: [COMPLEX]
The target audience (demographic or guidance) categorising the piece of content other than category and keywords.
value: (ENUM or IRI)
The value SHOULD BE selected from a standard list of values such as the EBU Intended Audience or Parent Guidance types.
guidanceText: (STRING or HTML)
A short human-readable editorial guidance message.
longGuidanceText: (STRING or HTML)
A long human-readable editorial guidance message.
notRated: (BOOLEAN)
A flag to indicate that the piece of content has not been rated (if set to true).
adultContent: (BOOLEAN)
A flag to indicate this the piece of content contains adult content (if set to true).
childrensContent: (BOOLEAN)
A flag to indicate this the piece of content is suitable for viewing by children (if set to true).
educationalContent: (BOOLEAN)
A flag to indicate this the piece of content is primarly intended for educational purposes (if set to true).
targetRegion: [COMPLEX]
The geographic target audience categorising the piece of content other than category and keywords. If no geographical targeting is provided, the piece of content is assumed to be applicable to all places, i.e. worldwide.
value: (TERRITORY)
The target country and region for the rating.
exclusive: (BOOLEAN)
A flag to indicate that the piece of content is available only in the target place specified in the value sub-field. If the exclusive attribute is omitted or has the value false then the piece of content is editorially targeted at the target place specified in the value sub-field.
format: (COMPLEX)
The editorial format categorising the piece of content other than category and keywords.
value: (ENUM or IRI)
The value SHOULD BE selected from a standard list of values such as the EBU Editorial Format types.
source: [COMPLEX]
Reference to the resources from which the piece of content is derived in whole or in part.
type: (ENUM)
The type of field SHOULD BE selected from a standard list of values (e.g. 'sketches', 'book', 'novel').
value: (STRING or HTML)
The source textual description.
language: (LANGUAGE)
The main production language of the piece of content. This may also be referrred as original language.
alternativeLanguage: [COMPLEX]
Alternative languages of the content and their use.
type: (ENUM)
The language purpose. The value SHOULD BE selected from the following list: audio, mainOriginalLanguage, mainDubbedLanguage, additionalOriginalLanguage, additionalDubbedLanguage, descriptiveVideoInformation, supplementalCommentary, directorCommentary, audioDescription, supplementaryAudioProgramme, educationalNotes, voiceOver, originalCommentary, dubbedCommentary, originalNarration, dubbedDialogue, dubbedNarration, interviewerLanguage, intervieweeLanguage, text, textDescription, transcript, caption, openCaption, closedCaption, supplemental, titles, subtitles, openSubtitles, closedSubtitles, songLyrics, signLanguage, dubbedSignLanguage. The main, production and original values SHOULD NOT be used as this complicates processing by the Consumer.
value: (LANGUAGE)
The alternative language value.
productionCountry: [TERRITORY]
The original country (or countries) where the piece of content was produced. The values SHALL BE an [ISO3166] (ISO, “ISO 3166,” .) "alpha 2" country code.
location: [COMPLEX]
Location information associated with the piece of content.
type: (ENUM)
The type of field SHOULD BE selected from a standard list of values (e.g. 'filming', 'depicted'). The main and production values SHOULD NOT be used as this complicates processing by the Consumer.
value: (PLACE or TERRITORY)
The actual geographical place or territory.
fictional: (BOOLEAN)
A Boolean value indicating whether the place is purely fictional.
temporal: [COMPLEX]
Temporal coverage information associated with the piece of content.
type: (ENUM)
The type of field SHOULD BE selected from a standard list of values (e.g. 'filmingPeriod', 'depictedPeriod').
value: (PERIOD or YEAR)
The actual temporal coverage period or gregorian calendar year.
fictional: (BOOLEAN)
A Boolean value indicating whether the temporal period is purely fictional (e.g. 'year 2030').
contentVersion: (STRING or NUMBER)
The version of the content.
position: (NUMBER)
The position of a particular piece of content within a container or collection (e.g. Collection, Programme, Programme Group, Series).
duration: (TIMECODE or DURATION or NUMBER)
The duration of a the pieces of content in seconds. Please note that the published duration may be different (see Section 8.4.13 (Programme Publication)). For Media Resources and Segments the value MAY be expressed as TIMECODE or DURATION.



 TOC 

8.4.3.2.  Links

supportingMaterial: [LINK]
Relates a piece of content to supporting material.
thumbnails: [LINK]
A list of thumbnail images or screen shots depicting the piece of content.



 TOC 

8.4.3.3.  Relationships

creator: [AGENT]
The creator of the piece of content.
publisher: [AGENT]
The publisher of the piece of content.
contributor: [AGENT]
Contributors to the piece of content. The following fields are additionally defined for the contributor relationship:
role: (ENUM or IRI)
REQUIRED. A Canonical Value representing the role played by the Target Entry as contributor (e.g. author, director, actor, producer). The value SHOULD BE selected from a standard list of values such as the European Broadcasting Union Role Codes [EBU‑ROLE‑CODES] (EBU, “European Broadcasting Union - Role Codes,” .). This is the Primary Sub-Field for the purposes of sorting and filtering.
roleLabel: (STRING)
A human-readable label or name associated to the role sub-field.
stageName: (STRING or HTML)
A human-readable label or name attributed to the person or organisation on stage (e.g. 'character name' or 'interviewer').
category: [CATEGORY]
One or more user-facing categories associated to the piece of content.
rights: [RIGHTS]
Content rights information. If the rights information is absent, no assumptions can be made about the status of these and other rights with respect to the piece of content.
crossPromotions: [CONTENT]
Relates a piece of content to other pieces of content which are cross-promotions (e.g. "if you liked this piece of content you may also like these other content items").
rel: (ENUM)
REQUIRED. The rel value MUST BE the "related" relation type as defined in [RFC5988] (Nottingham, M., “Web Linking,” October 2010.).



 TOC 

8.4.4.  Programme

The Programme object type extends the CONTENT object type and represents an editorially coherent piece of content. Defined as that which is created by a commissioning decision. For example, a TV/radio programme, movie or tune.



 TOC 

8.4.4.1.  Fields

country: [TERRITORY]
The countries and regions where the programme has been released.
firstTransmissionDate: (TIMESTAMP)
The first transmission or publication date and time.



 TOC 

8.4.4.2.  Relationships

ownership: (SERVICE)
Associate a Programme to the owner Service (e.g. the commissioner, national broadcaster service, content owner). In every metadata hierarchy only the top-level editorial object, whether a Brand, Series or Episode, must reference a owner Service. Objects below the root node may override this, specifying a different owning Service.
clips: [CLIP]
Associate a Programme to a clip (e.g. trailer, preview, interview).
awards: [AWARD]
A list of awards or awards nominations for a programme.
firstTransmissionChannel: (SERVICE)
The first transmission or publication service.
repeats: [SERVICE]
Information about the publication history of the programme. A repeated transmission or publication. The following fields are additionally defined for the repeats relationship:
date: (TIMESTAMP)
The repeat transmission or publication date and time.



 TOC 

8.4.5.  Programme Group

The Programme Group object type extends the PROGRAMME object type and represents a collection of Programmes that are grouped together, which are not Series or Brand. A Programme Group can contain Programmes or other Programme Groups. The Programme Group object type is identified with the string PROGRAMME_GROUP. For example, a collection of programmes, mini-Series, compilation, serial, concept, show, theme etc.



 TOC 

8.4.5.1.  Relationships

programmes: [PROGRAMME]
The list of Programmes inside the Programme Group (e.g. the list of Series part of a Brand or Episodes part of a Series).



 TOC 

8.4.6.  Brand

The Brand object type extends the PROGRAMME_GROUP object type and represents a collection of assets with a recognisable collective identity. A programme brand groups a collection of series and or episodes (e.g. 'American Idol').



 TOC 

8.4.7.  Series

The Series object type extends the PROGRAMME_GROUP object type and represents a succession of programmes with a standard format. A series groups a collection of series and/or episodes (e.g. 'Rai Due X Factor 2010').



 TOC 

8.4.8.  Programme Item

The Programme Item object type extends the PROGRAMME object type and represents a programme that can have versions (e.g. an episode, a clip). The Programme Item object type is identified with the string PROGRAMME_ITEM.



 TOC 

8.4.8.1.  Relationships

versions: [VERSION]
Different versions of a same episode or clip can exist. The relationship primary boolean flag SHOULD be used to flag the so called "canonical" or preferred version. No more than one version should be labelled as "canonical" because of the ambiguity this creates and this complicates processing by the Consumer.



 TOC 

8.4.9.  Episode

The Episode object type extends the PROGRAMME_ITEM object type and represents an editorial concept which groups one or more versions. Often when talking about a television programme what it is really meant is an episode. An episode could be simply be part of a brand a so called pilot episode.



 TOC 

8.4.10.  Clip

The Clip object type extends the PROGRAMME_ITEM object type and represents a short clip associated to a brand, a series or an episode. The Clip object type MAY also be used to represent online video clips generated by users.



 TOC 

8.4.11.  Version

The Version object type extends the CONTENT object type and represents a specific edit or version of a programme item. While there could be different version types (e.g. different run length, different parental guidance, alternative viewing angles etc.) only one is marked as original.

The addition of burned in accessibility features (e.g. hearing impaired, signed and dubbed audio described) to the video requires a separate editorial version from the original because these aspects of the presentation are generally not selectable by a user.

However, when such accessibility features are expressed using multiple external tracks (audio, video, text etc) associated and syncronized to the main audio and video tracks (see Section 8.4.23 (Media Group)) such differences SHALL be represented by multiple publications of the same basic editorial version since the underlying editorial content is identical at scene level. The same applies to certain types of technical variation, such as video resolution. For example HD and SD variations SHALL be represented by separate publications of the same editorial Version.



 TOC 

8.4.11.1.  Fields

original: (BOOLEAN)
A Boolean value indicating whether or not the Version is the original. Service Providers MUST NOT mark more than one Version as original="true", and MAY choose not to mark any Version as original, if this information is not available. For efficiency, Service Providers SHOULD NOT mark all non-original Versions with original="false", but should instead omit this sub-field for all non-original instances.



 TOC 

8.4.11.2.  Relationships

broadcasts: [BROADCAST]
The broadcast events associated with a particular version.
availabilities: [ONDEMAND]
The availabilities associated with a particular version when it is made available on-demand.



 TOC 

8.4.12.  Service

The Service object type extends the CONTENT object type and represents a publication outlet (e.g. a broadcasting service). A service is a collection of outlets which contain common material, but with some variations (e.g. by region). Hierarchies of services MAY be defined (e.g. radio, tv, online, mobile).



 TOC 

8.4.12.1.  Fields

serviceType: (ENUM)
The service type SHOULD BE selected from the following list: broadcast, virtual, iptv, ondemand, owning.
locator: (IRI)
A service locator per [DVB‑URI] (British Broadcasting Corportation and Condition-ALPHA, “Uniform Resource Identifier (URI) Scheme for Digital Video Broadcasting (DVB) Programme Resources,” March 2013.) (e.g. dvb://233a.1041.10bf).
lcn: (NUMBER)
The service Logical Channel Number (LCN).



 TOC 

8.4.12.2.  Links

logo: (LINK)
A logo or icon associated to the service.
rel: (ENUM)
REQUIRED. The rel value MUST BE the "icon" relation type as defined in [RFC5988] (Nottingham, M., “Web Linking,” October 2010.).
dog: (LINK)
A Digital On screen Graphic (DOG) associated to the service.
rel: (ENUM)
REQUIRED. The rel value MUST BE the "icon" relation type as defined in [RFC5988] (Nottingham, M., “Web Linking,” October 2010.).



 TOC 

8.4.12.3.  Relationships

outlets: [SERVICE]
Relates a Service to the Outlets that are contained within the Service. An outlet represents a service which does not have variations. For example, in the movie industry some movie publication or distribution ondemand outlets may be: on-air, online (payed, subscription, advertised), physical media (dvd, blu-ray, VHS), theatre (cinema), mobile.
organisation: (ORGANISATION)
Relates a Service to an Organisation providing the service.
application: (APPLICATION)
A reference to a media player or helper Application. A media player will be invoked to present all publications associated with an ondemand service. An on-screen helper application MAY be used instead to help users to provision IPTV services and resolve issues.



 TOC 

8.4.13.  Programme Publication

The Programme Publication object type extends the CONTENT object type and represents an instance or publication event of a Programme. The Programme Publication object type is identified with the string PROGRAMME_PUBLICATION. A programme publication is associated with a service, and with a particular version of a programme. For example, a programme instance on a broadcast or on-demand service.



 TOC 

8.4.13.1.  Fields

publishedDuration: (NUMBER)
The published duration of the Programme version in seconds. For broadcast publication events, when all the time parameters are provided, the published duration MUST be equal to the difference between end time and start time.



 TOC 

8.4.13.2.  Relationships

service: (SERVICE)
A reference to the Service on which the programme instance will be broadcasted or made available on demand.
programme: (VERSION)
A reference to the Programme version.
media: (MEDIA_RESOURCE)
A reference to the programme version AudioVisual media resource.
locator: (IRI or STRING)
The locator SHALL match the corresponding media resource locator field (see Section 8.4.22 (Media Resource)). Note that this sub-field is solely provided as a shortcut reference to the underlying media asset.



 TOC 

8.4.14.  Broadcast

The Broadcast object type extends the PROGRAMME_LOCATION object type and represents a publication event of a single Programme version on a single service at particular time (e.g. news at 21:00 on specific service). Multiple broadcast events can be grouped into a Schedule.



 TOC 

8.4.14.1.  Fields

start: (TIMESTAMP)
The published date and time at which the programme version broadcast will be starting.
end: (TIMESTAMP)
The published date and time at which the programme version broadcast will be ending.
firstShowing: (BOOLEAN)
A Boolean value indicating whether the programme version being broadcasted is a first showing.
lastShowing: (BOOLEAN)
A Boolean value indicating whether the programme version being broadcasted is a last showing.
repeat: (BOOLEAN)
A Boolean value indicating whether the programme version being broadcasted is a repeat.
live: (BOOLEAN)
A Boolean value indicating whether the programme version being broadcasted is a live broadcast.
free: (BOOLEAN)
A Boolean value indicating whether the access to the programme version being broadcasted is free.



 TOC 

8.4.15.  Ondemand

The Ondemand object type extends the PROGRAMME_LOCATION object type and represents an on-demand publication event designating a window of availability of a single Programme version on a particular service between two dates (e.g. catch-up on yesterday night 20:00pm soap opera).



 TOC 

8.4.15.1.  Fields

startAvailability: (TIMESTAMP)
The published date and time that the programme version will be available. If not specified the programme version is assumed to be available.
endAvailability: (TIMESTAMP)
The published date and time that the programme version will no longer be available. If not specified the programme version is meant to be made available indefinitely.
firstAvailability: (BOOLEAN)
A Boolean value indicating whether the programme version is made available for the first time.
lastAvailability: (BOOLEAN)
A Boolean value indicating whether the programme version is made available for the last time.
expiryDate: (TIMESTAMP)
The published date and time when the programme version expires or it is no longer available for viewing.
instantViewing: (BOOLEAN)
A Boolean value indicating whether the programme version is for instant viewing.
deliveryMode: (ENUM)
The on-demand pblication delivery mode such as 'streaming', 'download', 'progressive-download' etc. This string generally is specified to contain a valid Canonical Value from a reference data vocabulary. A Provider SHOULD use any additional deliveryMode values as necessary.



 TOC 

8.4.16.  Schedule

The Schedule object type extends the CONTENT object type and represents a group of broadcast events from the same service (e.g. ZDF service schedule).



 TOC 

8.4.16.1.  Fields

start: (TIMESTAMP)
Start of the period covered by the schedule.
end: (TIMESTAMP)
End of the period covered by the schedule.



 TOC 

8.4.16.2.  Relationships

service: (SERVICE)
A reference to the Service on which the programmes will be broadcasted.
broadcasts: [BROADCAST]
The list of broadcasts inside the schedule.



 TOC 

8.4.17.  Catalogue

The Catalogue object type extends the CONTENT object type and represents a group of on-demand publications from the same service (e.g. YouTube catalogue).



 TOC 

8.4.17.1.  Fields

catalogueType: (ENUM)
The catalogue type SHOULD BE selected from a standard list of values (e.g. 'catchup tv', 'VOD', 'SVOD' etc.).



 TOC 

8.4.17.2.  Relationships

service: (SERVICE)
A reference to the Service on which the programmes will be made available on-demand.
titles: [ONDEMAND]
The list of titles inside the catalogue.



 TOC 

8.4.18.  Application

The Application object type extends the CONTENT object type and represents an abstract application (e.g. BBC iPlayer). The Application object type is identified with the string APPLICATION.



 TOC 

8.4.18.1.  Fields

country: [TERRITORY]
The countries and regions where the application has been released.



 TOC 

8.4.18.2.  Relationships

ownership: (SERVICE)
Associate an Application to the owner Service (e.g. BBC Applications).
builds: [APPLICATION_BUILD]
Different builds of the same application can exist. The relationship primary boolean flag SHOULD be used to flag the so called "canonical" or preferred build. No more than one build should be labelled as "canonical" because of the ambiguity this creates and this complicates processing by the Consumer.



 TOC 

8.4.19.  Application Build

The Application Build object type extends the CONTENT object type and represents a specific build of an application (e.g. BBC iPlayer for iPad ver 2.0.4). For example a non-backwards-compatible change to the application would require modelling a different application build (e.g. BBC iPlayer for iPad with Retina). The Application object type is identified with the string APPLICATION_BUILD.



 TOC 

8.4.19.1.  Fields

original: (BOOLEAN)
A Boolean value indicating whether or not the application build is the original. Service Providers MUST NOT mark more than one application build as original="true", and MAY choose not to mark any application build as original, if this information is not available. For efficiency, Service Providers SHOULD NOT mark all non-original application builds with original="false", but should instead omit this sub-field for all non-original instances.



 TOC 

8.4.19.2.  Relationships

availabilities: [APPLICATION_PUBLICATION]
The availabilities associated with a particular Application Build when it is made available for download and installation.



 TOC 

8.4.20.  Application Publication

The Application object type extends the CONTENT object type and represents an instance or publication event of an Application. The application object type is identified with the string APPLICATION_PUBLICATION. An application is associated with a service, and with a particular application build.



 TOC 

8.4.20.1.  Fields

startAvailability: (TIMESTAMP)
The published date and time that the application build will be available. If not specified the application build is assumed to be available.
endAvailability: (TIMESTAMP)
The published date and time that the application build will no longer be available. If not specified the application build is meant to be made available indefinitely.
free: (BOOLEAN)
A Boolean value indicating whether the access to the application build is free or requires a payment.



 TOC 

8.4.20.2.  Relationships

service: (SERVICE)
A reference to the Service on which the application instance will be made available to download and installation (e.g. Apple iTunes Store).
build: (APPLICATION_BUILD)
A reference to the application build.
media: (MEDIA_RESOURCE)
A reference to the media resource representing the application package.
locator: (IRI or STRING)
The locator SHALL match the corresponding media resource locator field. Note that this sub-field is solely provided as a shortcut reference to the underlying media fragment.



 TOC 

8.4.21.  Application Gallery

The Application Gallery object type extends the CONTENT object type and represents a group of application publications from the same service (e.g. iTunes AppStore).



 TOC 

8.4.21.1.  Relationships

service: (SERVICE)
A reference to the Service on which the applications will be made available to download and install.
applications: [APPLICATION_BUILD]
The list of applications inside the application gallery.



 TOC 

8.4.22.  Media Resource

The Media Resource type extends the CONTENT object type and represents a digital or physical manifestation of a version. For an organisation or producer acting as caretaker for a media resource, it MAY contain a string formatted piece of information about a specific e.g. tape name, shelf location for an asset, including an organisation's name, departmental name, shelf id. and contact information. Differently for a data file or web video it MAY contain a IRI reference to the media resource and an optional type (e.g. for an HTML5 audio or video it would refer to the URL of the source and its type). The Media Resource type is identified with the string MEDIA_RESOURCE.



 TOC 

8.4.22.1.  Fields

locator: (IRI or STRING)
An identifier of the digital media resource or a string description where to find a physical source (e.g. dvb://scifi@2009-10-20T03:39:00Z/PT51M per [DVB‑URI] (British Broadcasting Corportation and Condition-ALPHA, “Uniform Resource Identifier (URI) Scheme for Digital Video Broadcasting (DVB) Programme Resources,” March 2013.) or a URI reference to a CDN streaming service, or a string like 'Archives building A, Row J, Shelf 2').
mediaType: (ENUM)
The media type of the media resource. The value is a hint about the type of the representation that is expected to be returned when the value field is dereferenced. Note that the type field does not override the actual media type returned with the representation. When specified the value MUST conform to the syntax of a MIME media type defined in [MIMEREG] (Freed, N. and J. Klensin, “Media Type Specifications and Registration Procedures,” December 2005.). Unless otherwise specified, the type value field MUST be a valid Canonical Value as defined by the IANA MIME Media Types registry [IANA‑MIMEREG] (IANA, “MIME Media Types,” .) includind any media type paramters, such as the "codecs" parameter [RFC4281] (Gellens, R., Singer, D., and P. Frojdh, “The Codecs Parameter for "Bucket" Media Types,” November 2005.). Note that the same Media Resource MAY be used to represent different versions when the media type is a container file or format.
medium: (COMPLEX)
The material or physical carrier of the resource. If a file, it should be the carrier format.
value: (ENUM)
The type of media resource SHOULD BE selected from a standard list of values such as the EBU Storage Media types (e.g. '1BM', 'BMX', 'video', 'audio').
length: (NUMBER)
The media resource size or length in octets. The value is a hint about the content length of the media resource representing the media resource and it does not override the actual content length of the representation as reported by the underlying protocol.
start: (TIMECODE or TIME or NUMBER)
The beginning point for playback of the media resource (e.g. 'seeking position').
audioEncoding: (ENUM)
The audio encoding parameters SHOULD BE selected from a standard list of values such as the EBU Audio Compression Codes.
audioConfiguration: (ENUM)
The audio configuration parameters SHOULD BE selected from a standard list of values such as the EBU Audio Format Codes (e.g. 'stereo', '2+1', 'surround', 'surround (7+1)').
audioBitrate: (NUMBER)
The audio bit rate.
minAudioBitrate: (NUMBER)
The minimal audio bit rate.
maxAudioBitrate: (NUMBER)
The maximum audio bit rate.
audioSamplingRate: (NUMBER)
The audio sampling rate.
audioLoudnessLevel: (ENUM)
The media resource loudness level in dB.
width: (NUMBER)
This value is a hint about the video's intrinsic or ideal width in pixels.
height: (NUMBER)
This value is a hint about the video's intrinsic or ideal height in pixels.
frameSize: (STRING)
The video frames size.
frameRate: (ENUM)
The video frames per second rate SHOULD BE selected from a standard list of values such as the EBU Video Frame Rate types.
aspectRatio: (ENUM)
The video aspect ratio SHOULD BE selected from a standard list of values such as the EBU Visual Aspect Ratio types.
colourMode: (ENUM)
The video colour mode SHOULD BE selected from a standard list of values such as the EBU Colour Codes.
videoEncoding: (ENUM)
The video encoding parameters. The value SHOULD BE selected from a standard list of values such as the EBU Video Compression Codes.
hd: (BOOLEAN)
A Boolean value indicating whether the video is high definition.
3d: (BOOLEAN)
A Boolean value indicating whether the video is 3D.
uhd: (BOOLEAN)
A Boolean value indicating whether the video is ultra high definition.
videoBitrate: (NUMBER)
The video bit rate.
minVideoBitrate: (NUMBER)
The minimal video bit rate.
maxVideoBitrate: (NUMBER)
The maximum video bit rate.
videoSamplingRate: (NUMBER)
The video sampling rate.
embedCode: (HTML)
An HTML fragment that, when embedded in an HTML page, will provide an interactive player UI for the media resource.



 TOC 

8.4.23.  Media Group

The Media Group object type extends the MEDIA_RESOURCE object type and represents a group of related media resources containing one or more versions. For example, a Media Group MAY BE used to express alternative representations for the same media resource or it MAY BE used to represent multiple external tracks (audio, video, text etc) associated and syncronized to the main audio and video tracks. The Media Group object type is identified with the string MEDIA_GROUP.

Note that a MEDIA_GROUP locator field MAY BE empty and instead one or more alternative media sources MAY specified. A Consumer MUST BE able to select the main alternative media source by stepping through each of the specified sources in the given order.



 TOC 

8.4.23.1.  Relationships

sources: [MEDIA_RESOURCE]
A list of alternative representations for the same media resource (e.g. alternative source files using different encodings/codecs made available to a web browser to play the same content).
tracks: [MEDIA_GROUP]
Used to describe alternative audio, video or text tracks syncronized with the main the media resource.
kind: (ENUM)
The type of track SHOULD BE selected from a standard list of values such as the HTML5 video track kind attribute, the EBU Audio Channel Purpose or Language Purpose codes (e.g. 'subtitles', 'captions', 'descriptions', 'signing', 'dubbing').
lang: (LANGUAGE)
The language of the track.
label: (STRING)
A human-readable label or name associated to the type sub-field. This is the Primary Sub-Field for the purposes of sorting and filtering.



 TOC 

8.4.24.  Segment

The Segment object type extends the CONTENT object type and represents a continuous portion of a piece of a programme version, for example a single topic in a news programme or the highlights of a soccer match. A particular segment can belong to a single programme only, but it can be a member of multiple segment groups. A programme can contain multiple segments. Segments are reusable, editorially distinct items.



 TOC 

8.4.24.1.  Fields

segmentType: (ENUM)
The type of segment SHOULD BE selected from a standard list of values (e.g. 'highlights', 'bookmarks', 'preview', 'insertion points', 'shots', 'speech').
start: (TIMECODE or TIME or NUMBER)
The beginning point for playback of the programme segment.
chapter: (BOOLEAN)
A Boolean value indicating whether the programme segment is a chapter.



 TOC 

8.4.24.2.  Relationships

programme: (VERSION)
A reference to the programme version this segment belongs to. If the segment is part of a segment group, this field MAY be left empty and the segment is assumed to belong to the programme as referenced by the parent segment group.
media: (MEDIA_RESOURCE)
A reference to the media resource representing the segment.
locator: (IRI or STRING)
The locator SHALL match the corresponding media resource locator field or contain a URI Media Fragment with a Normal Play Time (NPT) or SMPTE time code as defined in section 4.2.1 of [MEDIA‑FRAGMENTS‑URI] (W3C, “Media Fragments URI 1.0,” .). Note that this sub-field is solely provided as a shortcut reference to the underlying media fragment.



 TOC 

8.4.25.  Segment Group

The Segment Group object type extends the SEGMENT object type and represents collection of segments that are grouped together. A segment group can contain segments or segment groups. The Segment Group object type is identified with the string SEGMENT_GROUP.



 TOC 

8.4.25.1.  Relationships

segments: [SEGMENT]
The list of segments that are contained within the segment group. The order of the references to segments determines the temporal playback order of segments in this group.



 TOC 

8.4.26.  Content Collection

The Content Collection object type extends the CONTENT object type and represents a group or list of related pieces of content, and it has the following fields and relationships:



 TOC 

8.4.26.1.  Relationships

contents: [CONTENT]
The list of pieces of content that are contained within the collection.
rel: (ENUM)
REQUIRED. The rel value MUST BE the "item" relation type as defined in [RFC6573] (Amundsen, M., “The Item and Collection Link Relations,” April 2012.) when referring to a piece of Content part of a hierarchical collection of content. The rel value MUST BE the "collection" relation type as defined in [RFC6573] (Amundsen, M., “The Item and Collection Link Relations,” April 2012.) when referring to a piece of Content representing a hierarchical collection of content.



 TOC 

8.4.27.  Rights

The Rights object type extends the basic object type CONTENT and represents information (rights management statement or reference to a service providing such information e.g. via a URL) about copyright, intellectual property rights or other property rights held in and over a piece of content, stating whether access is open or restricted in some way.



 TOC 

8.4.27.1.  Fields

rightsType: (ENUM)
The type of rights expressed (e.g. 'merchandising', 'derivation', 'publication'). The value SHOULD BE selected from a standard list of values such as the EBU Rights Type codes.
exploitationIssues: (STRING)
Use to state any other restrictions, such as non-rights ones (e.g. legal).
rightsTemporal: (PERIOD)
The temporal coverage.
inclusionCountries: [TERRITORY or STRING]
An inclusion list of countries for whom the content is intended or useful. The special value 'all' is reserved to indicate all or any country.
exclusionCountries: [TERRITORY or STRING]
An exclusion list of countries for whom the content is intended or useful. The special value 'all' is reserved to indicate all or any country.
coverageType: (ENUM)
The coverage type (e.g. broadcast locally, regionally, nationally or internationally). The value SHOULD BE selected from a standard list of values such as the EBU Rights Type codes.



 TOC 

8.4.27.2.  Relationships

rightsHolder: (AGENT)
The person or organisation holding or managing the rights related to the piece of content.



 TOC 

8.4.28.  Award

The Award object type extends the basic object type CONTENT and represents an award or an award nominations for a programme.



 TOC 

8.4.28.1.  Fields

year: (YEAR)
Specify the year when the programme won or has been nominated.
awardCategory: (ENUM)
Specify the category in which the programme won the awards or the nomination. The value SHOULD BE selected from a standard list of values.



 TOC 

8.4.28.2.  Relationships

nominee: [AGENT]
A reference to the person or organisation who won the nomination.
recipient: [AGENT]
A reference to the person or organisation who won the award.



 TOC 

8.4.29.  Agent

The Agent object type extends the basic object type ENTRY and represents a person, organisation or group.



 TOC 

8.4.30.  Person

The Person object type extends the basic object type AGENT and represents a contact as defined in [PortableContacts] (Smarr, J., “Portable Contacts 1.0 Draft C,” .). This effectively means that a valid Portable Listings Person is a valid Portable Contacts Contact (see section 7.2 of [PortableContacts] (Smarr, J., “Portable Contacts 1.0 Draft C,” .)).



 TOC 

8.4.31.  Organisation

The Organisation object type extends the AGENT object type and represents an organisation or institution.



 TOC 

8.4.31.1.  Relationships

members: [AGENT]
The list of contacts inside the organisation.



 TOC 

8.4.32.  Group

The Group object type extends the AGENT object type and represents a group of people or organisations.



 TOC 

8.4.32.1.  Relationships

members: [AGENT]
The members of the group.



 TOC 

9.  IANA Considerations

A Entry object, when serialised to a byte stream using the JSON grammar, can be identified with the following media type:

MIME Media Type Name
application
MIME Subtype Name
listings+json
Required Parameters
none
Optional parameters:
"profile":
This parameter contains a whitespace-separated list of profile URIs used to express the Entries metadata as defined in Section 3.1 of [RFC6906] (Wilde, E., “The 'profile' Link Relation Type,” March 2013.). If this attribute is omitted implementations MUST process the media type as if the value was the string "http://portablelistings.net/profiles/core/1.0/".
Encoding Considerations
As defined for application/json in [RFC4627] (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.).
Security Considerations
As defined for application/json in [RFC4627] (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.).
Published Specification
This specification.
Applications that use this media type
No applications are currently known to use this media type.

The "Link Relation Types" registry has been updated with the following entries:



 TOC 

10.  Security Considerations

This memo abides by the security considerations of HTTP Basic Auth [RFC2617] (Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication,” June 1999.) and the OAuth protocol [OAuth 2.0] (, “The OAuth 2.0 Authorization Protocol,” .).



 TOC 

11.  Acknowledgements

This document would not be possible without the inspiring and seminal work of Joseph Smarr and other Open Stack community fellows and their Portable Contacts [PortableContacts] (Smarr, J., “Portable Contacts 1.0 Draft C,” .) specification. Either the document structure, design principles, the pragmatism and simplicity used to present the Portable Contacts specification has been key inspiration for the author to start designing a similar specification for a fairly different domain. Credits go also to the Atom community long standing work, especially their inspiring [ATOM‑PROFILES] (, “Atom Profiles Proposal,” .) and the JSON Syndication Format [JSON‑SYN] (, “JSON Syndication Format,” .) proposals. Other credits go to other past and present people which have collaborated with the author either in informal chats, brainstorming sessions and email discussions.



 TOC 

12.  Change Log

Changes from -03 version (Draft C)



 TOC 

13.  References



 TOC 

13.1. Normative References

[RFC2119] Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119, March 1997 (TXT, HTML, XML).
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” RFC 2616, June 1999 (TXT, PS, PDF, HTML, XML).
[RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication,” RFC 2617, June 1999 (TXT, HTML, XML).
[RFC3339] Klyne, G., Ed. and C. Newman, “Date and Time on the Internet: Timestamps,” RFC 3339, July 2002 (TXT, HTML, XML).
[RFC3987] Duerst, M. and M. Suignard, “Internationalized Resource Identifiers (IRIs),” RFC 3987, January 2005 (TXT).
[RFC4281] Gellens, R., Singer, D., and P. Frojdh, “The Codecs Parameter for "Bucket" Media Types,” RFC 4281, November 2005 (TXT).
[RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., “The Atom Syndication Format,” RFC 4287, December 2005 (TXT, HTML, XML).
[RFC4627] Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” RFC 4627, July 2006 (TXT).
[RFC5646] Phillips, A. and M. Davis, “Tags for Identifying Languages,” BCP 47, RFC 5646, September 2009 (TXT).
[RFC5988] Nottingham, M., “Web Linking,” RFC 5988, October 2010 (TXT).
[RFC6573] Amundsen, M., “The Item and Collection Link Relations,” RFC 6573, April 2012 (TXT).
[RFC6906] Wilde, E., “The 'profile' Link Relation Type,” RFC 6906, March 2013 (TXT).


 TOC 

13.2. Informative References

[ANSI-SMPTE-12M-1986] SMPTE, “SMPTE time code.”
[ATOM-MEDIA] Atkins, M., “Atom Media Extensions.”
[ATOM-PROFILES] Atom Profiles Proposal.”
[BBC-PROGRAMMES] BBC, “Programmes ontology.”
[DCMI-PERIOD] DCMI Period Encoding Scheme.”
[DVB-URI] British Broadcasting Corportation and Condition-ALPHA, “Uniform Resource Identifier (URI) Scheme for Digital Video Broadcasting (DVB) Programme Resources,” March 2013.
[EBU-OBJECTMODEL] EBU, “EBU Object Model.”
[EBU-REFERENCEDATA] EBU, “European Broadcasting Union - Metadata Reference Data.”
[EBU-ROLE-CODES] EBU, “European Broadcasting Union - Role Codes.”
[EBUCORE] EBU, “EBU – TECH 3293 - EBU Core Metadata Set (EBU Core) v.1.4.”
[GEO-JSON] The GeoJSON Format Specification.”
[HOSTMETA] Eran Hammer-Lahav, E., “Web Host Metadata.”
[HTML5] W3C, “HTML5 - A vocabulary and associated APIs for HTML and XHTML.”
[HTML5-MM] W3C, “Media Multitrack API.”
[IANA-MIMEREG] IANA, “MIME Media Types.”
[IANA-RELREG] IANA, “Link Relation Types.”
[ISO3166] ISO, “ISO 3166.”
[ISO8601-duration] ISO, “ISO 8601.”
[JSON-SYN] JSON Syndication Format.”
[MEDIA-FRAGMENTS-URI] W3C, “Media Fragments URI 1.0.”
[MEDIA-RSS] Yahoo! Inc. and RSS Advisory Board, “Media RSS Specification.”
[MIMEREG] Freed, N. and J. Klensin, “Media Type Specifications and Registration Procedures,” BCP 13, RFC 4288, December 2005.
[OAuth 2.0] The OAuth 2.0 Authorization Protocol.”
[OpenSearch] Clinton, D., “OpenSearch 1.1.”
[OpenSocial] OpenSocial Social API Server Specification 2.0 DRAFT.”
[PortableContacts] Smarr, J., “Portable Contacts 1.0 Draft C.”
[TV-ANYTIME] ETSI, “TV Anytime.”
[WEBFINGER] The Webfinger Protocol.”
[XRD] Extensible Resource Descriptor (XRD) Version 1.0 - Committee Draft 02.”
[XSD-DATATYPES] Biron, P. and A. Malhotra, “XML Schema Part 2: Datatypes Second Edition,” October 2004.


 TOC 

Appendix A.  Examples

Here is a sample request and response that illustrates much of Portable Listings. For simplicity, authorization information is not shown in the request.

Sample request (via HTTP GET):

GET /api/listings?startIndex=1&count=10&sortBy=displayName HTTP/1.1
Host: sample.site.org

Sample response (JSON):

HTTP/1.1 200 OK
Content-Length: ...
Content-Language: en
Content-Type: application/listings+json;
             profile="http://portablelistings.net/profiles/core/1.0/"

{
  "startIndex": 1,
  "itemsPerPage": 10,
  "totalResults": 8,
  "lang": "en",
  "entry": [
    {
      "id": "5E5EEBED3173",
      "objectType": "episode",
      "displayName": "Episode 1",
      "title": "Pilot",
      "alternativeTitle": {
        "type": "original",
        "value": "Northwest Passage"
      },
      "summary": "The small northwest town of Twin Peaks,
                  Washington is shaken when the body of Laura Palmer,
                  is discovered...",
      "alternativeDate": {
        "type": "originalAirDate",
        "value": "1990-04-08T00:00:00Z"
      },
      "tags": [
        "FBI", "murder", "twinpeaks"
      ],
      "genre": [
        {
          "value": "3.4.6.4",
          "label": "Crime"
        },
        {
          "value": "3.4",
          "label": "Drama"
        },
        {
          "value": "3.4.6.10",
          "label": "Thriller"
        }
      ],
      "language": "en",
      "alternativeLanguage": [
        {
          "type": "additionalOriginalLanguage",
          "value": "no",
          "label": "Norwegian"
        }
      ],
      "contributor": [
        {
          "href": "C675EDD23A2D",
          "role": "director",
          "label": "David Lynch",
          "primary": true
        },
        {
          "href": "C675EDD23A2D",
          "role": "writer",
          "label": "David Lynch"
        },
        {
          "href": "2F050A9AF481",
          "role": "writer",
          "label": "Mark Frost"
        },
        {
          "href": "94423F9D5AC7",
          "role": "actor",
          "label": "Kyle MacLachlan",
          "stageName": "Special Agent Dale Cooper"
        }
      ],
      "position": 1,
      "parent": {
        "href": "55835B5213C7",
        "label": "Series 1"
      },
      "peers": [
        {
          "href": "8881860D6F31",
          "label": "Episode 2",
          "rel": "next"
        }
      ]
    },
    {
      "id": "8881860D6F31",
      "objectType": "episode",
      "displayName": "Episode 2",
      "title": "Traces to Nowhere",
      "summary": "Cooper's investigation into the murder of
                  Laura Palmer continues, as her secret
                  boyfriend James Hurley is interrogated...",
      "contributor": [
        {
          "href": "3C67E1038205",
          "role": "director",
          "label": "Duwayne Dunham",
          "primary": true
        },
        {
          "href": "C675EDD23A2D",
          "role": "writer",
          "label": "David Lynch"
        },
        {
          "href": "2F050A9AF481",
          "role": "writer",
          "label": "Mark Frost"
        }
      ],
      "position": 2,
      "parent": {
        "href": "55835B5213C7",
        "label": "Series 1"
      },
      "peers": [
        {
          "href": "5E5EEBED3173",
          "label": "Episode 1",
          "rel": "prev"
        },
        {
          "href": "33D1096625D0",
          "label": "Episode 3",
          "rel": "next"
        }
      ]
    }
  ]
}



 TOC 

Appendix B.  Compatibility with EBUCore and other standards

This version of the Portable Listings specification is currently wire-compatible with the EBUCore standard. Additionally the specification is aligned and compatible with other Open Standards such as TV-Anytime, the BBC Programme ontology and HTML5 Video and Multitrack related specifications. The Person object type syntax and definitions is currenly wire-compatible with Portable Contacts, and consequently with the overlapping portion of the OpenSocial RESTful Protocol version 2.0 format [OpenSocial] (, “OpenSocial Social API Server Specification 2.0 DRAFT,” .). Note though that the API interfaces are not compatible and differ.

It is our intention to maintain this compatibility going forward, so long as it is feasible, and so long as the changes required are compatible with the Goals and Approach of this spec. Although Portable Listings is an independent spec, with a more limited scope than other broadcast and television industry and Web standards, any proposed changes to the Portable Listings spec SHOULD BE considered in the context of other communities, and we should strive not to break compatibility unless it is truly necessary, e.g. if the goals of different standard communities diverge significantly in the future.



 TOC 

Author's Address

  Alberto Attilio Reggiori
  Derrick Media
Email:  alberto@derrickmedia.com
URI:  http://www.derrickmedia.com/