W3C home > Mailing lists > Public > public-media-annotation@w3.org > September 2010

Response to your LC Comment -2394 on Media API spec

From: Thierry MICHEL <tmichel@w3.org>
Date: Wed, 29 Sep 2010 09:13:36 +0200
Message-ID: <4CA2E720.8080902@w3.org>
To: timeless@gmail.com
CC: "public-media-annotation@w3.org" <public-media-annotation@w3.org>
Dear Timeless (?),

The Media Annotations Working Group has reviewed the comments you sent 
[1] on the Last Call Working Draft [2] of the API for Media Resource 1.0 
published on 08 June 2010.
Thank you for having taken the time to review the document and to send 
us comments.

The Working Group's response to your comment is included below.
Please review it carefully and *let us know by email at 
public-media-annotation@w3.org if you agree with it or not*
before [09-Oct-2010].
In case of disagreement, you are requested to provide a specific 
solution for or a path to a consensus with the Working Group.
If such a consensus cannot be achieved, you will be given the 
opportunity to raise a formal objection which will then be reviewed by 
the Director during the transition of this document to the next stage in 
the W3C Recommendation Track.


For the Media Annotations Working Group,
Thierry Michel,
W3C Team Contact

2. http://www.w3.org/TR/2010/WD-mediaont-api-1.0-20100608

Resolution of the MAWG:

Response to the comments, we have copied your comments and added our 
answers to each of them inline ([MA]).
One comment is not done yet (for this we need to contact the HTML WG).

 > This specification defines a client-side API to access metadata
 > information related to media resources on the Web. The overall
 > purpose of the API is to provide developers with a convenient

I'd write "this API" instead of "the API" here and in the rest of this 
[MA] Agreed.

 > access to metadata information stored in different metadata formats.
 > Thereby, the Media Ontology Core Properties will be used as a pivot

"Thereby" is an odd word.
[MA] Removed "Thereby".

And given that you haven't introduced <MOCP>
until here, the entire sentence seems problematic. Typically I'd
expect someone to introduce briefly (one or two sentences) what
something (MOCP) is before saying that it will be used.
[MA] Added information on the Media Ontology Core Properties.

 > vocabulary in the API. The description of relations between these
 > core properties and the metadata formats in scope (1.2 Formats
 > in scope) are stored in the Media Ontology in order to provide

Does "Media Ontology" here refer to the same thing as MOCP earlier?
if it does, then you should indicate that you intend to use that short
form when you introduced it, if not, then you just used an undefined
[MA] Changed "Media Ontology" with a description of the Media Ontology 

 > cross-community data integration. The API is described using the
 > interface definition language [WEBIDL]. The decision to use Web IDL,
 > which offers bindings for ECMAScript and Java, can be based on the
 > Use Cases and Requirements for Ontology and API for Media Resource
 > 1.0 [MEDIA-ANNOT-REQS]. This document clearly states that the focus
 > for this API lies on multimedia services on the Web.

this should be "lies with" or "relies on"
[MA] Agreed.

 > The API serves as a mediator between a developer and the underlying
 > Ontology for Media Resource 1.0 [MEDIA-ANNOT-ONTOLOGY] with

drop "underlying", ontologies do not live below developers.
[MA] Agreed.

 > the goal to support interoperability between metadata formats. It offers

change "to support" to "of supporting"
[MA] Agreed.

 > operations to retrieve particular metadata informations represented in
 > a certain metadata format related to media resources on the Web.

 > This document is being published with the aspiration to gather wide

You don't want "aspiration", you could replace "published..to" with
"published in order to"
[MA] Agreed.

 > feedback on the yet available API design.

This doesn't make sense.
[MA] Dropped the sentence "This document is being published with the 
aspiration to gather wide feedback on the yet available API design.".

 > 1.1 Formats in scope
 > Refers to the formats in scope of Ontology for Media Resource 1.0.

 > 1.2 Formats out of scope
 > Refers to the Formats out of scope of Ontology for Media Resource 1.0.

 > 1.3 Terminology
 > In this document the terms "Media Resource", "Property", "Mapping"
 > and "Property value type" are to be interpreted as defined in Section
 > 2 of Ontology for Media Resource 1.0.

 > 2. Design consideration
 > We consider two scenarios where the API could be implemented:
 > either in a user agent (scenario 1) or as a web service (scenario 2).
 > The two scenarios are shown in the figure.

There's no figure here. Please name it (the figure is 2 paragraphs away).
[MA] Added a reference to the figure.

 > Scenario 1: User agent
 > The API is implemented in a user agent (e.g., browser or browser plugin)
 > and exposed as a JavaScript API (using the WebIDL JavaScript binding).
 > The user agent includes the components for metadata access (possibly

drop the "the" after "includes" and add an "and" before "possibly"
[MA] Agreed.

 > extraction) and mappings for a supported set of formats. The metadata
 > sources (the media resource and/or metadata document(s)) must be
 > retrievable and access (establish connection, retrieval) of the metadata

change "of" to "to".
[MA] Agreed.

 > sources is handled by the user agent.

Security considerations?
[MA] Security considerations are grouped in section 7.

 > Scenario 2: Web service
 > The API is implemented as a Web service. Such an implementation would
 > be typically used by a non-UI client, such as an agent harvesting 
 > However, the API could be also accessed from a user agent, and used the
 > same way as described in scenario 1 by the help of a JavaScript 
library for

change "by" to "with"
[MA] Agreed.

 > accessing the web service.

 > At the back-end of the web service, this scenario

you don't usually write 'back-end of the web service'.
and i'm not sure what this means.
[MA] Changed "back-end of the web service" to "In the implementation of 
the web service".

 > also allows supporting a media repository (e.g. content provider's 
 > database, movie store) from which the user agent could directly retrieve
 > metadata sources and which might have a custom metadata format not
 > supported by a user agent.

This doesn't make sense and is incredibly long for a single "sentence".
How could a user agent *directly* retrieve formats it doesn't support?
[MA] We have split up the sentence and removed "directly".

 > In contrast to an integrated component (see scenario 1), an 
 > of the API in a web service could do more complex mappings on the fly as

replace "as" with "than"
[MA] Agreed.

 > a component integrated in a user agent, and can be more flexible
 > (e.g., supporting additional formats).

 > Overview of different API options.

This alt text is woefully insufficient. It doesn't indicate that it's
a diagram. "JavaScript" is one word, not two.
[MA] Updated the figure and alt text.

 > In both scenarios, the access to the metadata properties needs the 
following stack of components:

drop the first "the"
[MA] Agreed.

 > * An implementation of the API for Media Resource (as defined in this
 > document), which providers the actual getter methods for the properties.
 > * An implementation of the mappings from a specific source format to the
 > properties of the media ontology (as defined in Ontology for Media 
Resource 1.0).

Why isn't "Media Ontology" written as a proper noun here?
[MA] Changed to "Media Ontology".

 > * A format specific API to access the metadata. This can be an API for
 > accessing 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 on which the API for Media Resource is 

change "on" to "with" and "working" to "applied"
[MA] Agreed.

 > it is assumed that there is at least a unidirectional reference from 
the media

why are you assuming things? -- this is an editorial complaint, the
statement needs to be active "one needs at least ..."
[MA] Agreed.

 > resource to the metadata document or vice versa. 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).

 > 3. API Description
 > The JavaScript examples in this document will only work if the API is 
 > by the browser.

 > The API exists of a number of interfaces, described using Web IDL.

change "exists" to "consists"
[MA] Agreed.

 > Implementations of the API should provide objects implementing the 
 > interfaces. The entire description can be found in Appendix A. The 
API is contained
 > within the MediaResource interface within the mawg module.
 > Objects implementing this interface provide the necessary methods to 
 > metadata properties of a Media Resource. The object holds methods to 
 > the actual Media Resource and the metadata sources. All properties can be
 > accessed through a specific operation getProperty.

... specific operation: getProperty.
[MA] Agreed.

 > When an attempt to read a property fails, diagnostics information can 
be obtained
 > using a diagnosis operation. Subtypes in the API are relevant for 
those properties
 > mentioned in 4.1.3 Core properties of Ontology for Media Resource 1.0.

 > Lastly, methods are available that allow to iterate through the 
available metadata.

change "to iterate" to "iteration"
[MA] Agreed.

 > Next, the different interfaces and exposed methods are discussed.
 > Finally, examples of the usage of the API can be found in section 4.

You can't use Lastly, Next and Finally as a set. -- And I'd suggest
that you avoid using "Lastly" entirely.
[MA] We have dropped "Lastly".

 > 3.1 MediaResource interface
 > The MediaResource interface offers a number of operations that allow
 > accessing the metadata of a Media Resource.

... provides a number of operations to access the metadata ...
[MA] Agreed.

 > Example on how to introduce this in HTML5 by making the HTMLMediaElement

change "on" to "of"
[MA] Agreed.

 > inherit from the MediaResource interface:

 > interface HTMLMediaElement : MediaResource, HTMLElement {...}

It seems like you're invading the HTML WG's namespace....
[MA] TODO The example indeed suggests this. We are contacting the HTML 
WG to see how we can progres with this topic.

 > As shown, the getElementsByTagName returns a HTMLMediaElement
 > which inherits from the MediaResource interface. The getProperty
 > method is part of this interface so the returned element has an
 > implementation of this method. By calling the getProperty method
 > with the argument "title" we can retrieve the title of the corresponding
 > media resource.

I don't think that getProperty is a good name for something that might
go into HTML DOM.
[MA] Changed "getProperty" to "getMediaProperty".

 > interface MediaResource {
 > boolean selectMAResource (in DOMString mediaResource, in optional 
MetadataSource[] metadataSources);
 > MAObject[] getProperty (in DOMString propertyName, in optional 
DOMString fragment, in optional DOMString sourceFormat, in optional 
DOMString subtype, in optional DOMString language);

getProperty is singular, it shouldn't be returning an array. Perhaps
[MA] The method allows to ask for a certain property (e.g., "title"), 
but the result can be plural in case different titles exist. Hence, we 
prefer to use the singular method.

 > DOMString[] getPropertyNamesWithValues (in optional DOMString 
 > in optional DOMString language, in optional DOMString fragment);

This is in plural, but again, it's icky.
[MA]Changed "getPropertyNamesWithValues" to "getPropertyNamesHavingValues".

 > DOMString[] getSourceFormatsWithValues (in optional DOMString language);

This is in plural, but again, it's icky.
[MA] This method has been dropped.

 > DOMString getDiagnosis ();

This is awful. Typically such things should be attributes. The
attribute name should be meaningful, this is not.
[MA] This method has been dropped. The getMediaProperty method will 
return a status code.

 > DOMString[] getOriginalData (in DOMString sourceFormat);

Data is a plural, but this should probably be getMAOriginalData or
getOriginalMAData ...
[MA] Changed "getOriginalData" to "getOriginalMetadata".

 > getDiagnosis
 > This operation allows to retrieve the status code(e.g., the 
getProperty operation returning a null value). See Section 4 for details.

I believe you should be using "function" or "method" instead of
"operation" (global comment).
[MA] "Operation" is the term used in Web IDL to denote "method".

Change "to retrieve" to "retrieval of" (globally).
[MA] Agreed.

You're missing a space between "code" and "(".
[MA] Agreed.

And splitting a return value out of a function for the null case is not 
very DOMish,
typically we'd use an Exception with the information in the exception
object. Why aren't you?
[MA] We removed the "getDiagnosis" operation so it is no longer split. 
Exceptions are not used due to objections brought forward in comments to 
earlier drafts

 > getProperty
 > This operation allows to retrieve the value of a certain property. 
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
 > MAObject interface, described in (MAObject interface). Depending on the
 > requested property, the returned objects implement a different 
 > (inheriting from the MAObject interface).

 > Requesting for the title gives back an array of MAObjects 
implementing the

This seems to be the first introduction of "title" (at least locally),
and it isn't marked up. It doesn't make sense. Perhaps:

Requesting "title" returns an array of MAObjects implementing the
[pre]Title[/] interface...
[MA] Agreed.

 > Title interface,

 > requesting the creator results in MAObjects implementing the Creator 
 > and so on. These interfaces are described in section 3.5 to 3.12.

 > propertyName DOMString ? ?
 > This argument identifies the property for which the values need to be 
 > Optional arguments allow to refine the request

replace "to refine" with "refining" and add a period to this "sentence"
[MA] Agreed.

 > language DOMString ? ?
 > This argument allows to identify the language of the metadata.
 > Only if the metadata is available in the specified language, the 
values are returned.

Values for the metadata will only be returned if it is available in
the specified language
[MA] Agreed.

 > Attributes
 > type of type DOMString
 > This attribute holds the type of the identifier, which can be 
filtered on in the
 > getProperty operation. Possible values are " UMID" and "ISAN".

You have a space inside the quotes around " UMID" which seems odd.
[MA] The "type" attribute was removed from the "Identifier" interface.

 > 3.5.2 Title interface
 > Title interface is used as the specific return type of 
 > method which has "Title" as a value of propertyName parameter.

the earlier request seemed to be for 'title', not 'Title' ...
[MA] Changed to "title".

 > Attributes
 > link of type DOMString
 > This attribute holds a link to the license if it is externally available.

Why is this a string instead of a url type?
[MA] Changed to "This attribute holds a URI, identifying the license if 
it is externally available."

 > organization of type DOMString
 > This attribute identifies the organization that issued the license.

 > type of type DOMString
 > This attribute holds the actual type of the policy, which can be 
filtered on in the getProperty operation. Examples are "license", 
"access", and "privacy".

 > value of type DOMString
 > This attribute holds the description of the license.

 > policy[0].value = "Attribution 2.5"
 > policy[0].organization = "http://creativecommons.org/licenses/by/2.5"
 > policy[0].type = "license"

Shouldn't organization be creative commons and the "link" property be
to the license?
[MA] "organization" has been removed.

 > This section introduces a set of status codes for the defined API to 
 > the system behaviour. It uses a subset of the HTML/1.1 [HTTP11] status

behaviour is the first word I can see which seems to be in en-GB
instead of en-US, I'd request that you consider whether your document
is in fact written in en-US and thus should use "behavior".
[MA] Agreed.

 > codes for general informations (e.g., bad request), but also system 


 > ones (e.g., property not defined in source format). The specific 
status codes
 > have been arranged in the HTML/1.1 [HTTP11] status codes categories.
 > These codes can be retrieved by calling the getDiagnosis method.

 > The set of status codes my be enlarged or changed in later versions of

Enlarged is odd.
[MA] Changed to "Later versions of this document may include additional 
status codes or other changes".

Later versions of this document may include additional status codes or
other changes.

 > this document. The numerical code range for the system specific status
 > codes start with x62 (x = number of HTML/1.1 [HTTP11] status codes
 > category and 62 = MA).

 > Numerical Code Textual Description Example
 > 200 Ok property delivered correctly

should be "OK"
[MA] Agreed.

 > interface MediaResource {
 > //Operation for retrieval of the reason of an error

this is really unhelpful.
[MA] The operation and comment were dropped.

 > DOMString getDiagnosis();

 > interface Rating: MAObject, Language {
 > attribute DOMString issuer;
 > attribute short value;
 > attribute DOMString type;

random indentation
[MA] Agreed.

 > interface Policy: MAObject, Language {
 > attribute DOMString link;

random trailing whitespace
[MA] Agreed.

 > interface FrameSize: MAObject {
 > attribute DOMString unit;

random trailing whitespace
[MA] Agreed.

 > Members of the Working Group are (at the time of writing, and by 
alphabetical order):

What about former members? :)

 > Members of the Working Group are (at the time of writing, and by 
alphabetical order):

you already said that.
[MA] Agreed.
Received on Wednesday, 29 September 2010 07:14:05 UTC

This archive was generated by hypermail 2.4.0 : Friday, 17 January 2020 16:24:43 UTC