Abstract

This specification defines an API to access metadata information
related to media resources on the Web. The overall purpose is to provide
developers with a convenient access to metadata information stored in
different metadata formats. The API provides means to access the set of
metadata properties defined in the Ontology
for Media Resources 1.0 specification. These properties
are used as a pivot vocabulary in this API. The core of this
specification is the definition of API interfaces for retrieving
metadata information in synchronous and asynchronous modes. It also defines
interfaces for structured return types along with the specification of
the behavior of an API implementation.

Status of This Document

This section describes the status of this document at the time of
its publication. Other documents may supersede this document. A list
of current W3C publications and the latest revision of this technical
report can be found in the W3C
technical reports index at http://www.w3.org/TR/.

This document has been reviewed by W3C Members, by software developers,
and by other W3C groups and interested parties, and is endorsed by the
Director as a W3C Recommendation. It is a stable document and may be
used as reference material or cited from another document. W3C's role in
making the Recommendation is to draw attention to the specification and
to promote its widespread deployment. This enhances the functionality
and interoperability of the Web.

No changes to this document have been made since the previous version.

The Metadata API for Media Resources may be implemented in both client-only
(built into a browser, as a plugin or as a JavaScript library) and
client-server (server-side as a Web Service). The level of
implementation of this API in these two scenario summarized in the implementation
report allowed to exit Candidate Recommendation. Nevertheless this
API is not expected to be implemented natively in the browser code.

1. Introduction

This specification defines an API to access metadata information
related to media resources on the Web. The overall purpose is to provide
developers with a convenient access to metadata information stored in
different metadata formats. The core
properties, defined in the Ontology for Media Resources 1.0
specification [MEDIA-ONTOLOGY],
will be used as a pivot vocabulary in this API. The description of
relations between these core properties and the metadata
formats in scope are documented in the Ontology for Media
Resources 1.0 specification [MEDIA-ONTOLOGY]
in order to provide cross-community data integration. This API is
described using the interface definition language Web IDL [WEBIDL]. The decision to
use Web IDL, which offers bindings for ECMAScript and Java, is based on
the Use Cases and Requirements for Ontology and Metadata API for Media Resources
1.0 [MEDIA-ANNOT-REQS].

This API defines interfaces that enable users/applications to consume
metadata in an interoperable manner. Interoperability between metadata
formats is ensured by the use of the Ontology for Media Resources 1.0
specification [MEDIA-ONTOLOGY]
as pivot metadata format. This API offers operations to request
particular metadata information represented in a certain metadata format
related to media resources on the Web. Further it specifies the actual
representation of the core
properties and the behaviour of this API.

1.2 Formats out of scope

1.3 Terminology

In this document the terms "Ontology", "Media Resource", "Property",
"Mapping" and "Property value types" are to be interpreted as defined
in Section 2
of the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY].

2. Conformance

In addition to sections marked as non-normative, all authoring
guidelines, diagrams, examples, and notes in this specification are
non-normative. Everything else in this specification is normative.

The keywords must, must not, required,
should, should not, recommended,
may, and optional
in this specification are to be interpreted as described in [RFC2119].

3. Design consideration

This section discusses different usage scenarios that led to design of
the API. We consider two main scenarios, where this API be implemented
and invoked:

in the User agent, or

as a client accessing a Web Service.

In both client-only and client-server cases of the implementation, the
media resources and/or the metadata sources are in many cases remote.
The API is by default specified as an asynchronous API, i.e., the calls
are not blocking, but results (or errors) are returned using a callback
mechanism. In order to better support the Web Service case, a
synchronous mode is also defined. The synchronous mode is optional.

This specification only defines the Metadata API for Media
Resources. Other components depicted in Figure 1 (e.g.,
access/extraction/storage of metadata) are not covered.

Scenario 1: Client-only (User agent)

In the first scenario, this API is implemented in the user agent,
i.e. built into a browser, as a plugin or as a JavaScript library.
Here, there exist three possibilities to invoke the API: by an
external calling code, an internal calling code behaving like a client
or it is attached as an extension to a user agent. Usually, such
implementations are an example for asynchronous processing. Besides
the Metadata API for Media Resources 1.0, the user agent may include components
for metadata access (and extraction) and mappings for a supported set
of formats, e.g., as defined in the property
mapping table of the Ontology for Media Resources 1.0
specification [MEDIA-ONTOLOGY].
Further, the metadata sources (the media resource and/or metadata
document(s)) must be retrievable. The access (e.g., establish
connection, retrieval) to the metadata sources is handled by the user
agent.

Scenario 2: Client-Server

In the second scenario, this API is implemented as a Web Service
following the principles of server-side synchronous processing. Such
an implementation would be typically used by a non-UI client, such as
an agent harvesting metadata. However, this API can be also accessed
from a user agent, and used the same way as described in scenario 1
with the help of a client-side library for accessing the Web Service.
In the implementation of the Web Service, this scenario also allows
supporting a media repository, e.g., content provider's archive
database, movie store. With the help of such a service the user agent
can retrieve metadata sources, which might have a custom metadata
format not supported by a user agent. In contrast to an integrated
component (see scenario 1), an implementation of this API in a web
service can do more complex mappings on the fly than a component
integrated in a user agent, and can be more flexible (e.g., supporting
additional formats).

In both scenarios, the API serves as a mediator between a client
application and the actual metadata sources. Interoperability is ensured
by defining i) operations for accessing the metadata information, ii) a
common object structure and iii) API behaviour (e.g., status codes).
Following this, an implementation has to implement this stack of
components:

An implementation of the Metadata API for Media Resources (as defined in
this document), which provides the actual GETTER methods for the
properties.

An implementation of the mappings from a specific source format to
the core properties. Here, the Metadata API for Media Resources 1.0 should use the Ontology for Media Resources
1.0 specification [MEDIA-ONTOLOGY],
where applicable.

A format specific API to access the metadata. This can be an API
for retrieving a metadata document describing a media resource (e.g.
an XML parser and a set of XPath statements) or an extractor to read
metadata embedded in the media resource (e.g. a library to read EXIF
information from JPEG images). In order to define the context in
which this API is applied, at least a unidirectional reference from
the media resource to the metadata document or vice versa is needed.
If this is not the case such a reference needs to be provided by the
web application (scenario 1), web service (scenario 2) or media
repository (scenario 2).

This API provides access to metadata information stored in
different metadata formats. As such, different instances of the same
property can exist.

4. API Description

This API defines a number of interfaces using [WEBIDL]. These can be
grouped in the following categories:

An interface defining the actual retrieval operations for metadata,
called MediaResource, and provided in both synchronous
and asynchronous versions (see Section 4.1,
Section 4.2 and Section
4.3)

An interface defining the data structure of response
objects/metadata annotations, called MediaAnnotation
and its specializations (see Section
4.4 and Section 4.5)

Next, the different interfaces and exposed operations are discussed.
Implementations of this API must
support asynchronous mode of operation, may
support the synchronous one and must
support the interfaces defined in this document. Instead of exceptions,
a status code indicating the state of processing (see Section
4.7) is returned (in the synchronous API) or provided via a
callback function (in the asynchronous API) in case an error occurs.

Then, the interfaces for the return types, i.e., MediaAnnotation
and its specializations, and MetadataSource are defined.

The IDL fragment in Appendix A of this
specification must be interpreted as required for conforming IDL
fragments, as described in the “Web IDL” specification. [WEBIDL]

4.1 MediaResource interface

The MediaResource interface is the core of this API and
provides operations to access the metadata properties of a specific
media resource. Here, a clear separation between asynchronous and
synchronous mode of operation has been achieved by defining two
implementing interfaces (derived from MediaResource), the AsyncMediaResource
and the SyncMediaResource interface. Objects of these
interfaces will be created by calling createMediaResource
of the MediaResource interface. The actual connection to
a specified metadata source will be created with the execution of the
getMediaProperty operation of AsyncMediaResource
or SyncMediaResource interface. The mediaResource
argument identifies the media resource, for which the implementation
of this API should try to find relevant metadata sources. Optionally,
references to metadata sources can be passed using an array of
objects, each implementing the MetadataSource interface (see Section
4.6).

4.1.1 Methods

createMediaResource

This operation instantiates an object of either AsyncMediaResource
or SyncMediaResource interface. Further, it allows
to set the specific media resource and metadata sources to which
this API is applied.

This attribute should specify the
desired mode of operation. 1 for
asynchronous and 2 for synchronous
mode should be used.
In the case the mode argument is omitted, and the
implementation supports both modes, the asynchronous mode
will be used.

4.2 AsyncMediaResource
interface

The AsyncMediaResource interface provides a number of
operations that allow accessing the metadata of a media resource. This
interface must be implemented.

Next, we give the Web IDL description of the AsyncMediaResource
interface and describe the different operations that are part of it.

In this section the MediaAnnotations
interface is used in the interface definitions. It serves as a
container to hold general values about properties enabling an
iteration over a set of different properties. Its definition can be
found in Section 4.4

4.2.1 Methods

getMediaProperty

This operation allows retrieval of the value of a specific
property, several or all properties in an asynchronous manner. The
specific property is passed as an argument and a list of objects
is returned that hold the values according to the requested
property. These objects implement the MediaAnnotation
interface, described in Section 4.4.
Depending on the requested property, the returned objects
implement a different subtypes (inheriting from the MediaAnnotation
interface). For example, requesting "title" gives back an array of
objects implementing the Title interface, requesting
"creator" results in objects implementing the Creator
interface and so on. These interfaces are described in Section
4.5. An example can be found here.

This argument holds a callback object
for asynchronous requests to the property. The successCallback
object implements the PropertyCallback
interface and holds a handleEvent operation
that needs to be called once all data for the requested
property is gathered. This handleEvent
operation needs to be called with a new MediaAnnotation
array.

This argument holds a callback object
for failure of asynchronous requests to the property. The
errorCallback object implements the ErrorCallback
interface and holds a handleEvent operation
that needs to be called if an attempt fails. This handleEvent
operation needs to be called with a new DOMString
representing the status code of the error (see Section
4.7 for details).

This argument contains a URI identifying
the specific media fragment for which the metadata is
requested. The URI must
conform to the URI for Media Fragment [MEDIA-FRAGMENTS]
specification. This parameter is optional.

This argument identifies a specific
metadata format. It should
use the metadata
format identifiers defined in the Ontology for
Media Resources 1.0 specification [MEDIA-ONTOLOGY].
If a metadata format is defined, only the metadata
available in the specified metadata format are retrieved.
This parameter is optional.

This argument allows to identify the
language of the metadata. Values for the metadata will
only be returned if it is available in the specified
language. Recommended best practice is to use BCP 47 [BCP47].
This parameter is optional.

This argument identifies a specific
metadata format. It should
use the metadata
format identifiers defined in the Ontology for
Media Resources 1.0 specification [MEDIA-ONTOLOGY].
If a metadata format is defined, only the metadata
available in the specified metadata format are retrieved.

This argument holds a callback object
for asynchronous requests for the original metadata. The successCallback
object implements the MetadataCallback
interface and holds a handleEvent operation
that needs to be called once all properties having values
are listed. This handleEvent operation needs
to be called with a new DOMString array holding the
original metadata.

This argument holds a callback object
for failure of asynchronous requests for the original
metadata. The errorCallback object
implements the ErrorCallback interface and
holds a handleEvent operation that needs to
be called if an attempt fails. This handleEvent
operation needs to be called with a new DOMString
representing the status code of the error (see Section
4.7 for details).

This argument holds a list of
objects with values according to the requested
property. These objects implement the MediaAnnotation
interface, described in Section
4.4. Depending on the requested property, the
returned objects implement a different subtypes
(inheriting from the MediaAnnotation
interface).

4.3 SyncMediaResource
interface

The SyncMediaResource interface provides a number of
operations to access the metadata of a media resource. This interface
may be implemented.

Next, we give the Web IDL description of the SyncMediaResource
interface for synchronous requests and describe the different
operations that are part of it. The MediaResource
defines a constructor that can be called to construct the object based
on an identifier of the media resource and optionally some metadata
sources.

In this section the MediaAnnotations
interface is used in the interface definitions. It serves as a
container to hold general values about properties enabling an
iteration over a set of different properties. Its explanation
can be found in Section 4.4

This argument contains a URI identifying
the specific media fragment for which the metadata is
requested. The URI must
conform to the URI for Media Fragment [MEDIA-FRAGMENTS]
specification. This parameter is optional.

This argument identifies a specific
metadata format. It should
use the metadata
format identifiers defined in the Ontology for Media
Resources 1.0 specification [MEDIA-ONTOLOGY].
If a metadata format is defined, only the metadata
available in the specified metadata format is retrieved.
This parameter is optional.

This argument allows to identify the
language of the metadata. Values for the metadata will
only be returned if it is available in the specified
language. Recommended best practice is to use BCP 47 [BCP47].
This parameter is optional.

This operation allows retrieval of the original metadata
according to the specified source format in a synchronous manner.
The operation returns a DOMString array holding the
status code of the request at the first and the original metadata
at the second position. An example can be found here.

This argument identifies a specific
metadata format. It should
use the metadata
format identifiers defined in the Ontology for
Media Resources 1.0 specification [MEDIA-ONTOLOGY].
If a metadata format is defined, only the metadata
available in the specified metadata format is retrieved.

4.3.2 Examples in Javascript

The examples in this section use getMediaProperty()
to get an object implementing the MediaAnnotation
interface. The noErrorStatus function ensures that no
error is present and the requested properties carry values.

We give some JavaScript examples on how to use the synchronous MediaResource
interface and it's operations.

4.4 MediaAnnotation
interface

MediaAnnotation interface is used as the return type of
MediaResource.getMediaProperty operation. It is a
container for holding general values about metadata properties.

As several metadata properties are defined as complex types, specific
derived types of MediaAnnotation have been defined,
adding their specific attributes. However, MediaAnnotation
can be used as a generic return type to access a printable string
representation of the property (in the value attribute).
It also includes a status code. In case of general errors, the first
element of the returned MediaAnnotation array contains
the global error code, otherwise the status can be given for each of
the returned properties.

The following design considerations have been used for specifying the
derived interfaces for each of the metadata properties:

For each metadata property, an interface is derived from MediaAnnotation,
adding typed attributes according to the specification in the
ontology document.

This API must fill value
with a printable string representation, it is recommended to follow
these steps:

use a name/label if present

for a URI

if a URI identifies a value known by this API, use the
appropriate label

dereference a URI to obtain a label, if possible

return the URI

create a string from the values of the set of attributes (e.g.
numeric values)

This approach possibly duplicates a string that is found in
another attribute in the value attribute. This is
considered as an acceptable amount of redundancy for the benefit of
having a generic value field for all metadata properties that can be
used regardless of the specific metadata property and data type of
the attributes.

If an attribute has type URI|string, the interface
shall have two attributes, one with "Link" and one with "Label"
appended to the attribute name, representing the URI and string
respectively

For consistency, this approach is also followed if the attribute
has only either URI or string as type.

This approach allows for user extensions by deriving from MediaAnnotation
or one of the derived interfaces for one of the metadata properties.

This attribute allows to specify the metadata source from which
the metadata was retrieved. It should
use the metadata
format identifiers defined in the Ontology for Media
Resources 1.0 specification [MEDIA-ONTOLOGY].

This attribute must be
filled with an printable string representation.

No exceptions.

4.4.2 Example in JavaScript

The noErrorStatus function ensures that
no error is present and the requested properties carry values. The MediaAnnotation
interface will be never instantiated - only instances of the derived
interfaces will be created. These must
be filled at least with the parameters specified in the MediaAnnotation
interface and may be filled
with the specific attributes.

4.5 Properties

This section describes the different properties that can be requested
through the MediaResource.getMediaProperty() operation.
When invoking this operation, objects implementing the MediaAnnotation
interface are returned that represent the specified property. All
properties are represented with an interface inherited from the MediaAnnotation
interface (following the design guidelines described above).

Several of the following return type interfaces can hold the value of
the property as both URI (i.e., a pointer to a controlled vocabulary)
or as free text. The URI is preferred, and the respective attribute of
the MediaAnnotation interface (or specialized type) shall be filled
whenever possible (i.e., when the information is included in or can be
constructed from the source metadata).

In the following, for each property, a (synchronous)
JavaScript example illustrates the usage of the property specific
attributes. In any case, the general attributes of the MediaAnnotation
interface could be also requested.

4.5.1 Identification Properties

4.5.1.1 Identifier

When the MediaResource.getMediaProperty operation
is invoked with "identifier" as a value of the propertyNames
parameter, an object implementing the Identifier
interface is returned representing the identifier property
(defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY].

4.5.1.2 Title

When the MediaResource.getMediaProperty operation
is invoked with "title" as a value of the propertyNames
parameter, an object implementing the Title
interface is returned representing the title property
(defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY].

4.5.1.3 Language

When the MediaResource.getMediaProperty operation
is invoked with "language" as a value of the propertyNames
parameter, an object implementing the Language
interface is returned representing the language property
(defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY].

4.5.1.3.2 Example in JavaScript

4.5.1.4 Locator

When the MediaResource.getMediaProperty operation
is invoked with "locator" as a value of the propertyNames
parameter, an object implementing the Locator
interface is returned representing the locator property
(defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY].

4.5.2 Creation Properties

4.5.2.1 Contributor

When the MediaResource.getMediaProperty operation
is invoked with "contributor" as a value of the propertyNames
parameter, an object implementing the Contributor
interface is returned representing the contributor
property (defined in the Ontology for Media Resources 1.0
specification [MEDIA-ONTOLOGY].

4.5.2.2 Creator

When the MediaResource.getMediaProperty operation
is invoked with "creator" as a value of the propertyNames
parameter, an object implementing the Creator
interface is returned representing the creator property
(defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY].

4.5.2.3 MADate

When the MediaResource.getMediaProperty operation
is invoked with "date" as a value of the propertyNames
parameter, an object implementing the Date interface
is returned representing the date property (defined in the
Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]).
This
property has been renamed from "Date" into "MADate" in order to
avoid naming conflicts with other objects named "Date" in web
applications.

4.5.2.3.1 Attributes

This attribute represents a date related to the media
resource. A date value must
be represented using one of the specific date/time data types
of XML Schema, depending on the available precision: gYear
gYearMonth, date, dateTime, or dateTimeStamp.

4.5.2.4 Location

When the MediaResource.getMediaProperty operation
is invoked with "location" as a value of the propertyNames
parameter, an object implementing the Location
interface is returned representing the location property
(defined inthe Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]).

4.5.3 Content Properties

4.5.3.1 Description

When the MediaResource.getMediaProperty operation
is invoked with "description" as a value of the propertyNames
parameter, an object implementing the Description
interface is returned representing the description
property (defined in the Ontology for Media Resources 1.0
specification [MEDIA-ONTOLOGY]).

4.5.3.2 Keyword

When the MediaResource.getMediaProperty operation
is invoked with "keyword" as a value of the propertyNames
parameter, an object implementing the Keyword
interface is returned representing the keyword property
(defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]).

4.5.3.3 Genre

When the MediaResource.getMediaProperty operation
is invoked with "genre" as a value of the propertyNames
parameter, an object implementing the Genre
interface is returned representing the genre property
(defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]).

4.5.3.4 Rating

When the MediaResource.getMediaProperty operation
is invoked with "rating" as a value of the propertyNames
parameter, an object implementing the Rating
interface is returned representing the rating property
(defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]).

4.5.4 Relational Properties

4.5.4.1 Relation

When the MediaResource.getMediaProperty operation
is invoked with "relation" as a value of the propertyNames
parameter, an object implementing the Relation
interface is returned representing the relation property
(defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]).

4.5.4.2 Collection

When the MediaResource.getMediaProperty operation
is invoked with "collection" as a value of the propertyNames
parameter, an object implementing the Collection
interface is returned representing the collection property
(defined inthe Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]).

4.5.5 Rights Properties

4.5.5.1 Copyright

When the MediaResource.getMediaProperty operation
is invoked with "copyright" as a value of the propertyNames
parameter, an object implementing the Copyright
interface is returned representing the copyright property
(defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]).

4.5.5.2 Policy

When the MediaResource.getMediaProperty operation
is invoked with "policy" as a value of the propertyNames
parameter, an object implementing the Policy
interface is returned representing the policy property
(defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]).

4.5.6 Distribution Properties

4.5.6.1 Publisher

When the MediaResource.getMediaProperty operation
is invoked with "publisher" as a value of the propertyNames
parameter, an object implementing the Publisher
interface is returned representing the publisher property
(defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]).

4.5.6.2 TargetAudience

When the MediaResource.getMediaProperty operation
is invoked with "targetAudience" as a value of the propertyNames
parameter, an object implementing the TargetAudience
interface is returned representing the targetAudience
property (defined in the Ontology for Media Resources 1.0
specification [MEDIA-ONTOLOGY]).

4.5.7 Fragments Properties

4.5.7.1 Fragment

When the MediaResource.getMediaProperty operation
is invoked with "fragment" as a value of the propertyNames
parameter, an object implementing the Fragment
interface is returned representing the fragment property
(defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]).

4.5.7.2 NamedFragment

When the MediaResource.getMediaProperty operation
is invoked with "namedFragment" as a value of the propertyNames
parameter, an object implementing the NamedFragment
interface is returned representing the namedFragment
property (defined in the Ontology for Media Resources 1.0
specification [MEDIA-ONTOLOGY]).

4.5.8 Technical Properties

4.5.8.1 FrameSize

When the MediaResource.getMediaProperty operation
is invoked with "frameSize" as a value of the propertyNames
parameter, an object implementing the FrameSize
interface is returned representing the frameSize property
(defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]).

4.5.8.2 Compression

When the MediaResource.getMediaProperty operation
is invoked with "compression" as a value of the propertyNames
parameter, an object implementing the Compression
interface is returned representing the compression
property (defined in the Ontology for Media Resources 1.0
specification [MEDIA-ONTOLOGY]).

4.5.8.3 Duration

When the MediaResource.getMediaProperty operation
is invoked with "duration" as a value of the propertyNames
parameter, an object implementing the Duration
interface is returned representing the duration property
(defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]).

4.5.8.3.2 Example in Javascript

4.5.8.4 Format

When the MediaResource.getMediaProperty operation
is invoked with "format" as a value of the propertyNames
parameter, an object implementing the Format
interface is returned representing the format property
(defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]).

4.5.8.5 SamplingRate

When the MediaResource.getMediaProperty operation
is invoked with "samplingRate" as a value of the propertyNames
parameter, an object implementing the SamplingRate
interface is returned representing the samplingRate
property (defined in the Ontology for Media Resources 1.0
specification [MEDIA-ONTOLOGY]).

4.5.8.5.2 Example in Javascript

4.5.8.6 FrameRate

When the MediaResource.getMediaProperty operation
is invoked with "frameRate" as a value of the propertyNames
parameter, an object implementing the FrameRate
interface is returned representing the frameRate property
(defined inthe Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]).

4.5.8.6.2 Example in Javascript

4.5.8.7 AverageBitRate

When the MediaResource.getMediaProperty operation
is invoked with "averageBitRate" as a value of the propertyNames
parameter, an object implementing the AverageBitRate
interface is returned representing the averageBitRate
property (defined in the Ontology for Media Resources 1.0
specification [MEDIA-ONTOLOGY]).

4.5.8.7.2 Example in Javascript

4.5.8.8 NumTracks

When the MediaResource.getMediaProperty operation
is invoked with "numTracks" as a value of the propertyNames
parameter, an object implementing the NumTracks
interface is returned representing the numTracks property
(defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]).

4.6.2 Examples in Javascript

4.7 API Status Codes

This section introduces a set of status codes for the defined API to
indicate the system behavior. As described in section
4.4, the status code is returned as one of the attributes of the
MediaAnnotation object returned by a method call to the
API. These status codes are used on the API level, and applied to
either client side or server side implementations.

Numerical Code

Textual Description

Example

200

OK

property delivered correctly

204

No Content

property retrieved without content

206

Partial Content

only a subset of the available data stored in the result set

400

Bad Request

syntactical error

404

Not Found

the queries resource is not found

415

Unsupported Media Type

get duration call on an image data store

462

Property not defined in Source Format

location is not defined in MediaRSS

500

Internal Server Error

internal library (e.g., extractor) crashes

562

Property not supported

a subset of properties implemented

5. Usage examples

5.1 Usage as JavaScript API

This part illustrates some examples how to use this API using
JavaScript in actual implementations. Moreover, in these examples it
is assumed that the implementation of this API knows where to find the
metadata that corresponds to a specific media resource (if necessary
the location of the metadata can be configured by the use of the MetadataSource
interface). The implementation should provide the mappings
of different metadata formats to the core
properties of the Ontology for Media Resources 1.0 specification
[MEDIA-ONTOLOGY]).

Example 1: Return the name of the director of the movie
"Apocalypse now".

5.2 Usage as Web Service

This part illustrates how this API could be implemented using web
services. Note that Web IDL currently does not provide bindings for
web services. The given examples correspond to the examples given in Section 4.5 for each property.

[{"Description":{"propertyName":"description","descriptionLabel":"Group picture of the W3C MAWG at the F2F meeting in Stockholm.","statusCode":200}}]

Request: http://example.com/my-media-resource/?ma-query=keyword

Response (JSON format):

[{"Keyword":{"propertyName":"keyword","keywordLabel":"meeting with people from outside the organisation","keywordLink":"http://sw.opencyc.org/2008/06/10/concept/en/MeetingWithOrganizationalOutsiders","statusCode":200}},{"Keyword":{"propertyName":"keyword","keywordLabel":"standardisation","keywordLink":"http://purl.org/vocabularies/princeton/wn30/synset-standardization-noun-1","statusCode":200}}]

[{"Relation":{"propertyName":"relation","targetLink":"http://www.w3.org/2008/WebVideo/Annotations/wiki/Image:MAWG-Stockholm-20090626_thumb.JPG","targetLabel":"Group picture of MAWG in Stockholm","typeLink":"http://www.ebu.ch/metadata/cs/ebu_HowRelatedCS.xml#19","typeLabel":"thumbnail","statusCode":200}}]

Request:
http://example.com/my-media-resource/?ma-query=collection

Response (JSON format):

[{"Collection":{"propertyName":"collection","collectionLink":"http://individuals.example.com/JohnDoe/myWorkPictures/","collectionLabel":"My Work Pictures","statusCode":200}}]

Request: http://example.com/my-media-resource/?ma-query=copyright

Response (JSON format):

[{"Copyright":{"propertyName":"copyright","copyrightLabel":"All images in the collection are copyrighted by John Doe.","holderLabel":"John Doe","holderLink":"http://individuals.example.com/JohnDoe","statusCode":200}}]

[{"TargetAudience":{"propertyName":"targetAudience","audienceLink":"http://www.mpaa.org/ratings/what-each-rating-means#NC-17","audienceLabel":"No One 17 and Under Admitted","classificationSystemLink":"http://www.mpaa.org/ratings","classificationSystemLabel":"MPAA","statusCode":200}}]

6. Implementation Notes

This section contains recommendations for implementators for handling
missing or multiple identifiers of media resources/fragments as well
as for interoperability of implementations.

6.1 Multiple identifiers of media
resources or fragments

In some source formats, it could be possible to identify the resource
or one of its fragments in multiple ways, e.g. by one or more
identifiers, fragment name or temporal/spatial fragment URIs. For
example, there could be a temporal media fragment, which can be
addressed by the time range, that also has an assigned ID.

In the RDF representation of the Ontology for Media Resources, this
can be represented (as recommended in the guidelines) by using owl:sameAs.
To ensure a similar behaviour in the API, an implementation should return all such identifiers in a
response. If queries to properties of a fragment with multiple
identifiers are made, the implementation should
accept each of the alternative identifiers and return the same
response for each of them.

6.2 Missing fragment identifiers

There are source formats, which may contain metadata about a fragment
(e.g. a track) without specifying any kind of identifier for it. For
the RDF representation this is not a problem, as blank nodes can be
used. In an API implementation, a client requesting the list of
fragments cannot query properties of a fragment in case there is no
identifier.

An implementation should
generate an identifier for the fragment in such a case and should ensure that it is valid for a
sufficiently long time so that the client can use it in subsequent
queries to properties of fragments. The identifier is not guaranteed
to remain permanently valid.

This can be implemented in different ways, including the following:

In a session-aware environment (e.g., in the user agent, in a web
service environment with session handling), the identifier could be
bound to the session and remain valid at least for the duration of
the session.

In a stateless environment, the identifier could be the same for
all clients and remain valid a defined time after it has been last
used (i.e., part of a query or response).

The identifier could be defined to be unique and permanent. In
that case the implementation has to manage the assignment of
identifiers to metadata sources.

6.3 Interoperability of
Implementations

The API can be implemented in two different modes. The asynchronous
mode is mandatory while the synchrounous one is optional. In this
context, interoperability between these modes would be a desired
feature in order to provide both processing modes based on the
implementation of one mode only.

An implementation of the optional synchronous mode of the API (e.g.
in a Web Service) is turned into the mandatory asynchronous
communication by a wrapper. Therefore the required wrapper
functionality is implemented in JavaScript using the Web Workers
specification [WEBWORKERS]
processing non-blocking scripts. A demo of the wrapper code can be
downloaded from [MAWG-REPO].
First, the existing operations of the MediaResource interface are
adapted in order to support the synchronous as well as asynchronous
mode (mawg_api.js). Then, the implementation of the
AsyncMediaResource interface wrapping the synchronous communication is
added. Therefore, the two operations of the AsyncMediaResource
interface (getMediaProperty and getOriginalMetadata)
refer to the corresponding synchronous calls by Web Workers (media_property_worker.js,
media_property_worker.js). Finally, the result of the
synchronous communication is pushed forward to the synchronous
operation by invoking a callback function.

Wrapping an asynchronous implementation by an synchronous call is
infeasible in JavaScript since threads cannot be suspended and
interact with concurrent ones. Nonetheless, another programming
language (e.g. Java), can be used to warp asynchronous API calls in
web service calls.

7. Security Considerations

This specification defines a API to access metadata information
related to media resources on the Web. These APIs will provide means
for requesting metadata information, which can already be accessed
in one or different formats, either as separate document or embedded
in media resources. As such, this API introduces no additional
security issue.

One should nevertheless note that some metadata could be used to
access personal information about someone without declaration of
agreement. For example, temporal and geographic information about a
media resource could indirectly provide information about its
creator.

There are related activities and technical documents in W3C working
on this topics, such as Policy Requirements [POLICY-REQS] in DAP
WG, ODRL 1.1 [ODRL11],
P3P 1.1 [P3P11]
and PLING Wiki [PLING-WIKI].