Re: [W3C Media Annotation WG] Request for Expert Review

Dear Soohong, all,

Here is now my feedback on the API document.

On Tue, Mar 16, 2010 at 3:17 PM, Soohong Daniel Park
<soohong.park@samsung.com> wrote:
>
> [2]
>
> API for Media Resource 1.0 [Version 09 March 2010]
>
> http://www.w3.org/TR/2010/WD-mediaont-api-1.0-20100309/
>
> Abstract: 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 access to metadata
> information stored in different metadata formats. The API will be introduced
> in an abstract manner using the interface definition language Web IDL.
> Thereby, the Media Ontology Core Properties will be used as a pivot
> vocabulary in the API.


FEEDBACK ON API:

1. Section 2.1: MAObject

You need to introduce MAObject better. What is it for? IIUC it is the
parent class to all return types - i.e. it is a generic list of
attributes for any property. I am not actually sure it is that useful
- in an application, that is information about the transcoding. I
would probably prefer if the properties were subclassed from a
MetadataSource object. But I am not sure you need that, either.


2. Section 2.1: Language

I would not define Language as a part of the return value of some of
the properties - it is very unlikely that a annotation uses different
languages for different properties. I would only manage the language
on the level of the metadata source level.


3. Section 2.2: setContext

I would suggest renaming that function. Also, your parameters are not
quite right:

boolean setMAResource ( in DOMString mediaResource, in optional
MetadataSource[] metadataSources);

(note the replacement of "Object" with "MetadataSource").


3. Section 2.3

You need to make sure that the full definition of "getProperty" is
printable (for me, it went off the right edge of my page).

Also, you only return one MAObject IIUC, so don't make the return value a list.

Also, I believe that the API should be independent of a format and
thus the sourceFormat and the subtype parameters are not useful.

Also, I believe the API should be independent of the language in use -
if you really wanted language selection to be made on the metadata
files, then this should be handled at a different level.

Further, I believe your "fragment" parameter may also refer to data
tracks in media resources, which I find a more important parameter
than all the other optional one, so would prefer to have that as the
second parameter.

Thus, it should probably look like:

MAObject getProperty(in DOMString propertyName, in optional DOMString fragment);

Note that I am not quite sure how to represent in Web IDL that the
MAObject is the union of all the possible return values for all
getProperty requests. I don't think how it is currently done is quite
correct, since it only returns the parent class, not the child
classes.

Further, I would suggest as an example for how to introduce this into
a UA: the  following example for how to introduce it into HTML5:

interface HTMLMediaElement : HTMLElement {
  ...
  getter MAObject getProperty(in             DOMString propertyName,
                                            in optional unsigned long
trackIndex);
  ...
}

(I don't think any other type of fragment than the track index makes
sense for HTML5).


4. Section 2.3.1.1 Identifier

Your examples are all a bit incomplete in their JSON representation. I
will write a full example for this section - the others need to be
changed logically to this, too, though I will only indicate this where
it may be confusing.

Example:
Identifier.value =
"http://www.w3c.org/2008/WebVideo/Annotations/wiki/Image:MAWG-Stockholm-20090626.JPG"
Identifier.type = "URI"

Usage as a service:
* Request: http://example.com/my-media-resource?ma-query=identifier
* Response in JSON:
{    "Identifier": {
           // This first lot is inherited from MAObject, though I am
unclear what the values should be
            "unstructuredValue": ???,
            "uri" : ???,
            "sourceFormat": ???,
            "fragmentIdentifier": ???,
            "mappingType": ???,
        "value":
"http://www.w3c.org/2008/WebVideo/Annotations/wiki/Image:MAWG-Stockholm-20090626.JPG",
        "type": "URI"
     }
}

Usage as a UA call in JavaScript in a Web Browser:

video = document.getElementByTagName("video")[0];
id = video.getProperty("identifier");

Resulting in:
id.value = "http://www.w3c.org/2008/WebVideo/Annotations/wiki/Image:MAWG-Stockholm-20090626.JPG"
and id.type = "URI"
and the other values as above in JSON


5. Section 2.3.1.2 Title

* remove "Language" from the inheritance list - should not be per
property but per metadata resource

* Example should be:
title.value = "MAWG Stockholm 20090626"
title.type = "Video title"

* JSON response should be as in the identifier example above

* add a UA JavaScript example as above

* similarly adapt 2.3.1.3 Language, 2.3.1.4 Locator


6. Section 2.3.2.1 Contributor

* why are we suddenly using "id" and "role" as attribute values? They
should continue to be "value" and "type" like in the previous
properties for consistency.

* in this example, you have a set of return values, so the spec needs
to look different:

interface Contributors {
    attribute DOMString value;
    attribute DOMString type;
}

interface Contributor: MAObject {
    attribute Contributors[] contributor;
}

* JSON reply thus looks something like:

{    "Contributor": {
           // This first lot is inherited from MAObject, though I am
unclear what the values should be
            "unstructuredValue": ???,
            "uri" : ???,
            "sourceFormat": ???,
            "fragmentIdentifier": ???,
            "mappingType": ???,
            "contributor": [ {
                     "value": "http://individuals.example.com/Contributor1",
                     "type": "editor"
                     },
                     {
                     "value": "http://individuals.example.com/Contributor2",
                     "type": "producer"
                     }]
     }
}


7. Section 2.3.2.2 Creator

* replace "StringObject" with "Creator"

* again, the value is a list, so it has to be something like:

interface Creator: MAObject {
  attribute DOMString[] values;
}

* the JSON looks something like:

{    "Creator": {
           // This first lot is inherited from MAObject, though I am
unclear what the values should be
            "unstructuredValue": ???,
            "uri" : ???,
            "sourceFormat": ???,
            "fragmentIdentifier": ???,
            "mappingType": ???,
            "values":
["http://individuals.example.com/Author1","http://individuals.example.com/Author2"]
     }
}


8. Section 2.3.2.3 CreationDate

* you talk about both "CreationDate" and "Date" here. If you want this
value to have a type of e.g. "creation date" and "publish date", it
should not be called "CreationDate", but only "Date".

*also, this may possibly return a list of dates rather than just one value


9. Section 2.3.2.4 Location

* your response value should be a JSON list something like:

{    "Location": {
           // This first lot is inherited from MAObject, though I am
unclear what the values should be
            "unstructuredValue": ???,
            "uri" : ???,
            "sourceFormat": ???,
            "fragmentIdentifier": ???,
            "mappingType": ???,
          "name": "San Jose",
          "longitude": 37.3398...,
          "latitude": -121.88...,
          "altitude": 0,
          "system": "GPS"
     }
}



10. Section 2.3.3.1 Description

* replace "StringObject" with "Description"


11. Section 2.3.3.2 Keyword

* replace "StringObject with "Keyword"

* there should be a list of values:

interface Keyword: MAObject {
  attribute DOMString[] value;
}


12. Section 2.3.3.3 Genre

* replace "StringObject" with "Genre"


13. Section 2.3.4.2 Collection

* replace "StringObject" with "Collection"


14. Section 2.3.5.2 Policy

* replace "Policy" with "License" as it is called in the Ontology (or
do it the other way roung)
* replace "policy" attribute with "value"
* add a "link" attribute (or something similar) with a link to the license text

interface License: MAObject {
  attribute DOMString value;
  attribute DOMString link;
  attribute DOMString organization;
  attribute DOMString type;
}

* example needs to map the fields


15. Section 2.3.6.1 Publisher

* replace "StringObject" with "Publisher"
* publisher does not have a need for a language attribute


16. Section 2.3.8.1 FrameSize

* Request should use the correct property name: replace
"technical-properties" with "frameSize"


17. Section 2.3.8.4 Format

* doesn't need a language attribute
* replace "StringObject" with "Format"
* interface should be:

interface Format: MAObject {
  attribute DOMString value;
}


18. Section 2.3.8.5 Samplingrate

* replace "UnsignedLongObject" with "Samplingrate"

* example should have a common samplingrate for audio, e.g. 44100 Hz


19. Section 2.3.8.6 Framerate

* replace "FloatObject" with "Framerate"


20. Section 2.3.8.7 Bitrate

* you should rename it to AverageBitrate - anything else doesn't
really make sense in the context of modern codecs
* should be provided in kbps (kilobit per second)
* replace "FloatObject" with "AverageBitrate"
* example value could be more useful, e.g. 45.06 kbps


21. Section 2.4 getDiagnosis

* the request should not have a "=" at the end of the URI
* same for 2.5.1 and 2.5.2 examples


22. Section 2.5.3 getOriginalData

* the return value should not be a DOMString list - it's simply a
single, very long string for the requested source format - not for all
possible formats

* in the examples, the quotes (") inside the string need to be escaped


23. Section 3

* if you introduce all the examples above for web service and for user
agent scenarios, you might not need this section


24. Section 4

* mentions "setting metadata" - I am not sure that can be done easily
across formats actually ... I'd be curious how you will realise that


Uff, got through the sections! I am quite happy with the documents
overall, so please take my feedback as improvements on an already good
set of documents.


Best Regards,
Silvia.

Received on Monday, 5 April 2010 12:15:23 UTC