Issues for LC

Open issues of Ontology doc for going LC

1. Your CSS reduces the margins between <p> elements throughout the document, which makes it harder to read. In general, please don't override very generic core styles from W3C as it defeats the purpose of having a common style. (by wonsuk)

2. You have definitions but aren't using <dfn>, it would be nice.  (I will be handled later.)

3. You don't define what an ontology is, I wouldn't assume that people actually know. (by John)

4. "defined in this Working Group" The draft shouldn't talk about the WG except in the SotD and possibly in notes and issues; this should probably say "defined in this specification". (by wonsuk)

5. Note that as per the Manual of Style it is usually recommended to use title case for titles. (by wonsuk)

6. Have you considered not using XML Schema for the types and instead relying on the more commonly used and less scary definitions provided by HTML5? I believe that given the target audience (as I understand it) it would be more useful. See http://dev.w3.org/html5/spec/infrastructure.html#common-microsyntaxes. Also note that you say your URI type is RFC3986/7 but reference XML Schema 1.0 part 2 which says anyURI is from RFC2396/2732. If you plan on keeping the reference to XML Schema, I would recommend upgrading to 1.1, even though it is still in LC. (by Florian)

7. The table in 4.1.2 is really hard to read. Is it necessary to cram all that information so closely together? I think that it would be clearer if the table subsections became simple subsections, and if the content were unfolded for each property, perhaps with a <dl> or something similar. (by Veronique)

8. Where does the "ma" prefix come from? It is described later as the "namespace" but it seems to be a prefix instead (and should be defined before being used). I may have missed it but the document does not seem to define a namespace for the vocabulary. Or maybe it's using a different meaning of "namespace", in which case that should be clarified. (by Joakim)

9. ma:identifier and ma:locator
It seems to me that these always contain identical information. Your examples in the API document indicate this, too. So, it might make sense to remove ma:identifier or retarget it towards giving it something more like a XML ID field than a URL. At minimum, your example in the API doc should be an example for when the value for these two fields is different. (by wonsuk)

10. Another major issue is that the specification as currently written has no discussion of conformance. What does it mean to implement this specification? What does it mean to conform to it? Some parts of it are described as normative, but there isn't a single normative assertion in it (no "must", a few "should", a couple "recommended" but none of them with a clear product to apply to). I understand that it may be difficult to write concrete tests for an ontology since it does "do" anything, but I still think that there could be clearly defined conformance requirements on products that expose this data model, e.g. that they must expose this or that property as a list of pairs of foo,bar, etc. The SotD states that this document is on Recommendation track, but it reads much like a Note (which might be fine as well, that's up to you). (by John)

11. updating the reference for making clear the normative and non-normative(by wonsuk)

12. add ogg mapping table to the mapping table (refer the action item)(by Thierry)

Open issues of API doc for going LC

• (1) 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? (It's done. but there are a few problems related with browsers.)

• (2) 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. (by Florian)

• (3) Title: Why just "Album title" and "Song title"? A *lot* of other things can have titles. (by wonsuk)

• (4) Section 2.3.2.3 CreationDate (by Wonsuk and John)

- 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

• (5) Section 2.3.5.2 Policy (The example for link attribute should be added by Florian)

-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

• (6) Section 2.3.8.1 FrameSize (by wonsuk)

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

• (7) "Section 2.3.8.4 Format (by wonsuk)

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

interface Format: MAObject {
  attribute DOMString value;
}"

• (8) "Section 2.3.8.5 Samplingrate (by wonsuk)

- replace ""UnsignedLongObject"" with ""Samplingrate"" - example should have a common samplingrate for audio, e.g. 44100 Hz"

• (9) "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. (by Chris and wonsuk)

• (10) The interfaces aren't clear as to whether they have constructors, in what scope, etc. (by Florian)

• (11) There are pretty much no conformance clauses, normative statements, testable assertions, etc. This is a concrete API, it must be testable. (by John)