Review of API for Media Resource 1.0

Hi,

I just noticed something, shouldn't it be API for Media Resource*s*? Same comment for the Ontology document.

Here are my notes on [0]:

ed.: "Thereby, the Media Ontology Core Properties will be used as a pivot vocabulary in the API." I don't think that the "thereby" is needed here. (same thing further down)

ed.: "the metadata formats in scope (1.2 Formats in scope) are stored in the Media Ontology in order to provide cross-community data integration" Instead of "are stored in the Media Ontology" I think you mean "are documented in the Ontology for Media Resources specification", no?

ed.: "The JavaScript examples in this document will only work if the API is implemented by the browser." That's probably not true, you could have an implementation of the API running in Javascript outside the browser. You might wish to say instead something like "The examples provided in this specification use Javascript, but they ought to be simple to translate to another language if there binding is implemented there."

ed.: "The API exists of a number of interfaces" -> The API has a number of interfaces

ed.: "Implementations of the API should provide objects implementing the different interfaces." That's not clear, I would expect that implementations MUST support these interfaces. How those are made available as objects ought to be clear from the WebIDL.

substantial: "Example on how to introduce this in HTML5 by making the HTMLMediaElement inherit from the MediaResource interface:" This shouldn't be an example. If a user agent is expected to expose this interface on media elements, then this has to be a MUST, possibly using an "implements" statement.

ed.: in getDiagnosis, "See Section 4" links to section 5.

substantial: Parameters that are optional in WebIDL need to be marked as "optional" instead of using the OPTIONAL 2119 keyword in the prose.

substantial: The general getProperty/getDiagnosis architecture seems skewed. I wonder if the API does not do more than what is actually required. I presume that when a getProperty request is made, all the metadata has already been loaded in memory and is available for immediate retrieval.

If that is not the case, the API *really* needs to be made asynchronous, otherwise it won't be usable in a browser context at all (or in any kind of performance-conscious environment, such as typically a web server).

If it is the case, then instead of specifying a complex filter in getProperty's parameters, it would be a lot simpler to just expose the property and leave it up to code to do the filtering. So instead of

  props = mr.getProperty("title");
  props = mr.getProperty("title", "#subchapter");
  props = mr.getProperty("title", null, "tva");
  props = mr.getProperty("title", null, null, null, "fr");

you would just have

  props = mr.title;

and leave it up to code to perform any kind of filtering on its own terms. This can then be abstracted into a library. It seems clearer, and much more idiomatic.

substantial: getDiagnosis doesn't seem thread-safe, and I'm guessing that even in a JS context it could easily hit race conditions. Is conveying the exact reason why something was null really a strong use case in JS? If so, wouldn't an exception work? If not (which is what I suspect) this could be dropped. I doubt anyone would use it — in fact your examples never do!

substantial: I suggest exposing the properties directly on the object and removing getPropertyNamesWithValues.

ed.: "MAObject" is not a very descriptive name, 75% of it is dedicated to saying that it's an object, which one already knows from the fact that it has been retrieved as such. "MediaAnnotation" would be clearer.

substantial: Would it not be simpler to replace getSourceFormatsWithValues with a sourceFormats array that could be filtered in code if one so desires? Is it even an important use case in the browser to list which metadata formats are available in general?

substantial: I'm sorry but I don't understand what selectMAResource is supposed to do. Does it allow one to change the underlying resource which the current object is describing and load another one? If so, it should be asynchronous (and it should also be on another interface). What does the boolean which it returns mean? Or maybe it's loading additional external metadata? Again, if so, it really needs to be asynchronous (and probably somewhere else too).

ed.: It's probably worth indicating that the Language interface is meant to be inherited from, that it doesn't do much on its own.

substantial: It is not clear "plain text" is for unstructuredValue. Is this the raw binary for binary formats? A piece of XML for XML formats?

substantial: What is the syntax of sourceFormat? Of mappingType? Of fragmentIdentifier?

substantial: Why is there a value field on Identifier if it's holding a URI that could be in the uri field it inherits from MAObject? Same for Locator, Creator.

substantial: The "usage as a service" segments aren't precise enough and normative enough to describe a protocol properly. I think that this document should limit itself to describing an API using WebIDL, and then either help define a REST binding for WebIDL or another document should be created for the protocol.

substantial: It is quite counter-intuitive to have:

  var lang = foo.getProperty("language").value;

when one could equally have:

  var lang = foo.language;

The same applies to other properties, such as description.

substantial: "For the latter a number of suggested terms are defined". If there is to be a controlled vocabulary, it needs to be in the ontology, not in the API. And "suggested" isn't really good, it's a MUST, a SHOULD, etc.

substantial: The section CreateDate has just "Date" in the interface name. It should probably be "CreationDate" in both.

substantial: Why is it "createdate" in getProperty and createDate in the service URI? Are all those property names the local names from the ontology? I can't see that defined anywhere.

substantial: Your Location interface seems to overlap with equivalent interfaces defined by the Geolocation WG. I strongly recommend that you coordinate with them to return a similar interface.

substantial: (In Relation) "For the latter a number of suggested terms are defined:" but no list follows. And the same comments apply as above for "suggested" and controlled vocabularies.

substantial: In general it would be a lot easier to read if interface attributes linked to the definition of the property in the ontology — especially if it is supposed to have a specific syntax. I didn't review each interface in great detail because going back and forth between the two documents to check that they were properly related was too tedious.

ed.: For FrameSize, it says that the default unit is pixels, yet in the example float values are returned for unitless objects. Is that intentional?

substantial: It's unclear what to return for Compression. Is JPEG a compression? Something more specific? Is it case sensitive? Partially controlled?

ed.: Why is it Samplingrate instead of SamplingRate?

substantial: The relationship of section 5 to HTTP is unclear. Is this needed?

substantial: Section 7 should be beefed up. Notably, if I can access geographic information it could be used to access someone's location without them agreeing to it. Likewise for name and a number of other things. In general, you probably need to think about privacy.

note: integration with DAP's Media Capture is likely desirable.


[0]http://www.w3.org/2008/WebVideo/Annotations/drafts/API10/LC/Overview.html

-- 
Robin Berjon - http://berjon.com/

Received on Tuesday, 17 August 2010 17:09:33 UTC