RE: Review of API for Media Resource 1.0

Dear Robin,

Thanks for the thorough review!
It seems indeed that the document is holding statements of different
versions which is the main cause of confusion.

I have updated the document according to some/most of your changes, further
modifications and revisions are planned.

Please see my (personal) comments below ([CP]).

Kind regards,
Chris


Ghent University - IBBT
Faculty of Engineering
Department of Electronics and Information Systems (ELIS)
Multimedia Lab Gaston Crommenlaan 8 bus 201
B-9050 Ledeberg-Ghent
Belgium
 
t: +32 9 33 14959
f: +32 9 33 14896
t secr: +32 9 33 14911
e: chris.poppe@ugent.be
 
URL: http://multimedialab.elis.ugent.be


-----Original Message-----
From: public-media-annotation-request@w3.org
[mailto:public-media-annotation-request@w3.org] On Behalf Of Robin Berjon
Sent: dinsdag 23 maart 2010 16:42
To: public-media-annotation@w3.org
Subject: Review of API for Media Resource 1.0

Hi,

this review is personal (i.e. neither as Vodafone nor DAP chair), and is
based on the http://www.w3.org/TR/2010/WD-mediaont-api-1.0-20100309/ draft.

• Abstract: "The API will be introduced in an abstract manner", I don't
think it's in the future (this is repeated later).
[CP]Changed.

• Similar comments as made previously concerning the custom CSS (I have to
disable that rule in Firebug to make the document readable).
[CP] Could you refer me to these previous comments, it is not clear to me
what the problem is.

• "It offers GET operations" Is this a statement of adherence to REST or
simply an indication that access is read-only?
[CP] The latter, I have changed this since the sentence should be clear by
itself.

• Typos: "addtion", "unstructeredValue", "uri's" -> "URIs", "determins"
[CP]Changed.

• What is a MAObject, what does it represent? It's very hard to understand
what the field mean without a clearer definition. Is it just intended as a
base class for all media annotations? Wouldn't calling it MediaAnnotation be
clearer than MAObject?
[CP] It is indeed meant to be a base class for all media annotations. I can
see why it is not clear so I have moved this section to the paragraph
describing the return type of the getProperty method (section 2.3).
Concerning the actual name I do not have strong favor for one or the other.


• I find the usage that is made of WebIDL and corresponding descriptions
hard to read. There are tools like ReSpec, Anolis, and others that make
generating clear and marked up WebIDL easy; they might be worth
investigating. (Compare with how interfaces are defined in any DAP draft, or
in the File API for instance.)
[CP] Interesting! Action items on this have been assigned and started in
today's telco.

• The description says that MAObject has a language attribute, but it's
really on Language.
[CP]Changed. 

• I am guessing that the attributes of MAObject have constraints beyond just
being DOMStrings, but they don't appear to be specified.
[CP] There could indeed be constraints (like a limited list of possible
values for sourceFormat and mappingType). Other are on syntax (like URI,
which is currently not supported in WebIDL). 

• All the MAObject attributes are created as read-write, but it seems
unclear what happens on setting.
[CP] Currently we do not consider the setting of properties, this is the
main reason for not including readonly in the WebIDL description

• The text about the two implementation scenarios seems out of place — what
is its relationship with the WebIDL above? Isn't it introductory? The second
scenario contradicts earlier statements according to which this is a client
API, and confuses me as to the exact scope of the specification — is it not
just intended as a JS API to get metadata out of documents?
[CP] I have moved the WebIDL to a more appropriate place, which makes the
implementation scenarios better placed.


• I personally don't see what the two diagrams add in terms of comprehension
— if anything, it should go into the text. My personal recommendation would
be to remove them but if the WG decides to keep them they should probably be
converted to an accessible graphics format such as SVG so that the text that
they contain can be read, enlarged, searched, etc.
[CP] I don't see the harm of having these diagrams, I agree on the
SVG-format.

• 2.2: I don't understand the first paragraph at all, and following that I
don't understand what interface setContent() is on.
[CP] Makes sense, the content of this paragraph is wrong due to different
versions. I have updated the paragraph. The setContext() method is used to
identify the Media Resource and metadata sources to which the API gives
access. 

• MetadataSource seems to be created in passing, without much explanation as
to what it really means.
[CP] I assume that the updated paragraph gives more information on this.

• Similarly, I don't understand section 2.3, or where getProperty() is meant
to be. All I can surmise is that it must be getting a property, somehow, on
something, and that it seems more complicated than I like methods to be, but
maybe that's just a feeling because I don't see what it does.
[CP] The getProperty method gives the values (encapsulated as an array of
MAObjects) for a certain metadata property (identified by "propertyName").
The method is complex due to the optional parameters.
In case of a JS implementation, an object would implement the MediaResource
interface. This object holds the different methods for identifying the
current Media Resource and metadata, for accessing the properties (through
the method getProperty()), for error diagnosis, and for iterating through
properties.
What is your opinion on this approach? If this is not clear from the text,
maybe we need to add a paragraph on this (or show example code in JS)?
This method is the core of the API so if it is not clear to you, it is
doubtful that it will be clear to others...

• In addition to more detail in the descriptions, examples would help. For
instance, converting Mozilla's File API + EXIF parser to your API might be
interesting.
[CP]Indeed

• I don't understand the examples for "identifier". In fact I don't
understand the whole section. It says that it implements the StringObject
interface, but StringObject just has a "value" field and Identifier also has
a "value" field — and it doesn't inherit from StringObject but from
MAObject. The example then goes on to list an array of one string, when one
would expect (from the description) an array of object literals containing
the fields defined on Identifier and inherited from MAObject. The usage as a
service then makes it more confusing. And it's not clear what interface the
identifier attribute (is it that?) is on.
[CP] Indeed, the description is wrong. The returned objects implement the
"Identifier" interface. The examples are (or should be) restricted to the
return values according to the specific interfaces (so to the "Identifier"
interface in this case). The example for identifier is indeed an older
version and I have updated this.

• Pretty much the same comments apply to all the other properties.

• Title: Why just "Album title" and "Song title"? A *lot* of other things
can have titles.
[CP] Indeed, the actual subtypes have not been defined yet.


• What is the relationship between language in 2.3.1.3, and the Language
interface? Why is the StringObject defined here and what is it meant to do?
[CP] The language in 2.3.1.3 is the language of the metadata, the Language
interface is actual metadata (so for instance the language of a document).
The StringObject is used to hold a DOMString value, while still inheriting
from the MAObject.


• I skipped over all the other properties because I simply cannot understand
enough of their description to review the document. I am sorry, I don't
intend to be mean, but I find this document to be mostly incomprehensible.
How about starting with several examples and modelling the WebIDL sections
on existing specifications?
[CP] What do you mean with existing specifications?

• "API for retrieval of reason of an error" Is there a reason to use this
approach instead of an error callback or an exception? Note that what
getDiagnosis() is supposed to be called on is unclear.
[CP] It was claimed  before that exceptions are not favorable. It is not
clear to me what you mean with the last sentence of this remark. The
getDiagnosis operation is part of the MediaResource interface, so objects
that implement this interface provide ways to call this operation. The
operation by itself should be called when getProperty returns a null value
for instance. (Currently it is not defined when this could happen, this is a
topic that will be discussed when the WG starts talking about the test
suites I assume).

• Long names like getPropertyNamesWithValues() and
getSourceFormatsWithValues() are unpopular and for good reason. This isn't
supposed to be a Java API!
[CP] Related to your remark on the MAObject I have no real favor for one or
the other.

• The XML examples in 2.5.3 use xsi:schemaLocation, which is very probably
an XML bad practice and certainly best avoided in an example.
[CP] Changed

• There are serious security concerns with this API, notably in terms of
privacy as geo data can be exposed alongside time, which is a great way of
tracking someone.
[CP] Indeed, but I think this is not really an issue specific to our API,
but rather to online multimedia content in general

• Appendix A loses me yet again, it seems to be saying something different
from the previous sections.
[CP] Appendix A is just the collection of all methods and interfaces into a
WebIDL module. I have revised this to correspond to the WebIDL descriptions
in the document. Can you explain what is wrong with this?

• The interfaces aren't clear as to whether they have constructors, in what
scope, etc.
[CP] I am not sure that we should describe the constructors in the
interfaces, probably an investigation of existing WebIDL API specifications
will clarify this.

• There are pretty much no conformance clauses, normative statements,
testable assertions, etc. This is a concrete API, it must be testable.
[CP] I agree, the definition of test suites is on our agenda.


With respect, this document is not at all ready for LC. As a first step I
recommend devising a few examples that cover the API's intended usage, and
then taking inspiration from existing API specifications in terms of how to
describe WebIDL, then redoing a review to see where it's at.

Best of luck!

--
Robin Berjon
 robineko — hired gun, higher standards
 http://robineko.com/

Received on Tuesday, 30 March 2010 12:10:46 UTC