Re: ACTION-158: review the API document

2009/10/10 Pierre-Antoine <pierre-antoine.champin@liris.cnrs.fr>

> 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.
>


The successor of RFC 4646 has been approved recently, see
http://tools.ietf.org/html/rfc5646 . The best thing is to refer to BCP 47,
that is the "latest link" version of "language tags" and "matching of
language tags". See http://www.rfc-editor.org/rfc/bcp/bcp47.txt

Requiring compliance with BCP 47 is fine, since language tags created under
this RFCs "sequence" (1766, 3066, 4646, RFC 5646) are backward-compatible.
E.g. an RFC 5646 language tag is an 1766 language tag - but not the other
way round.

Best,

Felix



> - 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
>
>