ACTION-158: review the API document

Dear all,

I have also reviewed the current draft of the API document. It also lead 
me to re-read the ontology document, on which I also have some comments, 
regarding its relation with the API.

I think some parts of the Ontology document may belong to the API 
document: the definition of datatypes (Ont:3.1), and the Syntactic Level 
Mapping (Ont:4.2.1.2).

I also think, as Raphaël suggested in a recent telecon, that the 
ontology document should specify the range of its property, but at a 
conceptual level. This would require introducing a few concepts such as 
Agent (for creator/contributor), Duration... Links to existing 
ontologies could be given (reusing their term directly?? maybe).

Then the API document would specify how those types are *represented* 
for the purpose of the API -- which is done by the various interfaces 
given by the document.

Other remarks:
- is the NoValue exception really necessary? Doesn't WebIDL have some 
long of 'null' value?
- I would suggest that attributs returning a list of objects use the 
plural form; e.g. 'creators' instead of 'creator'
- I suggest that 'contributor' return a list (hence become 'contributors')
- I suggest that Language is *required* to comply with RFC4646, or this 
will hinder interoperability.
- is it ok that the unit for Duration is fixed to 'second'? Can all used 
units be converted exactly to seconds? is a granularity of seconds 
always sufficient for duration?
- is it ok for the bitrate to be a number? What about Variable Bit Rate? 
Or would we raise NoValue in that case? (might be an option... after all 
we dont seek exhaustiveness)
- it is not clearly explained what the 'context' of a rating is.

Typos and minor remarks:
- in the abstract *and* section 1: "provide developers an convenient" -> 
"provide developers with a convenient"
- in the abstract "Media Ontology Core Properties" should link to the 
ontology document
- in the secton about License, the interface of the return value is not 
give,
- in the section about Compression, the given interface is FrameSize

I have other remarks, somehow deeper, but that shouldn't prevent us from 
publishing the first draft, I think.

   pa

Received on Friday, 9 October 2009 16:22:01 UTC