Edit comment LC-2418 for Media Annotations Working Group

Quick access to

Previous: LC-2417 Next: LC-2393

Comment LC-2418
Commenter: Robin Berjon <robin@berjon.com>

Resolution status:


sorry for being so late in reviewing your document! I see that you were planning to handle the comments at your September F2F however, so I hope that it isn't too late!

Here goes:

ed.: While I'm a big fan of using pedantic plurals I have reservations about using "musea" straight in the abstract, especially as many readers will already have been scared by "ontology" (an issue which you nicely defuse up front). If you do insist on using "musea", then at the very least you ought to be consistent and not use "museums" later (as you do).

ed.: "to foster the interoperability among" -> remove "the"

ed.: You have a CSS rule that sets margin-{top,bottom} to 0.3em on li and p. This makes your document quite hard to read, I have to go tinker with it in Firebug in order to go through it. Please don't change some of the fundamental style rules from the basic W3C style.

ed.: "of media resources hat describe" -> that

ed.: "The vocabulary is defined in this document is based" -> drop the first "is"

ed.: "usessyntacticmappings" Spaces!

ed.: The first parahraph of the introduction is a large chunk of text that talks about several different things. It would be worth splitting it into units of meaning that can be digested one by one.

ed.: You have several instances of things like:

"This section is informative, except those parts that are explicitly defined as normative."
"This section is normative; however, examples contained in this section are informative."

That muddles things up a little. DAP specs normally all have a section called "Conformance" (it's generated automatically, e.g. http://dev.w3.org/2009/dap/contacts/#conformance) that says "As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative." Then each section is either normative or it's not — without specific exclusion rules.

Section 1 also says that it has normative content, but it doesn't!

ed.: "defined in API for Media Resources 1.0 s well as" -> as well as

substantive: "The Working Group MAY potentially modify these definitions, to ensure compatibility with the return data types defined in API for Media Resources 1.0 s well as the data types defined in the HTML5 W3C Working Draft." This is strange to have in an LC document. An LC document is expected to be stable (i.e. the WG believes that it could go to CR). If the WG is going to change the definition of type values, that's a fundamental change that will require another LC. So either the types are final and this should be removed (which downgrades this to an editorial comment), or the WG should make the necessary changes and re-issue an LC.

ed.: "has defined a namespace URI, ma-ont, for use with this specification" The string "ma-ont" isn't the namespace URI that the group has defined (as this sentence seems to suggest), it's just a conventional prefix used in this document.

ed.: "As specifications that use this namespace URI progress through the standardization process, it is important that each subsequent revision of specifications that use this namespace MUST use the same namespace URI." There are several things that are wrong here. First, if it's not the same namespace URI then it can't be the same namespace, so this is self-evident. Also, it's unclear what the product is that the MUST applies to. Likewise for the following "MAY" (though I understand what it is trying to say.

I think that the solution here is to drop the normative statements since they are untestable (you're not going to write a test suite that can validate that MUST applied to future specifications). Simply replace the whole thing with "This namespace URI is expected to remain the same throughout the evolution of this ontology, even in the case new properties are added to it, so long as it remains backwards compatible. If however a new version were produced that was not backwards compatible, the WG reserves the right to change the namespace URI."

ed.: "The ma abbreviation is a prefix for the namespace http://www.w3.org/ns/ma-ont." Anything can be a prefix for that namespace, I think you mean to say that throughout this specification you use that as the conventional prefix. I'm not sure what its relationship to "ma-ont" is though.

substantial: "Applications that are compliant with this specification SHOULD use this namespace." What are the cases in which this rule has an exception?

substantial: "A controlled vocabulary such as [BCP 47] SHOULD be used." What are the cases in which this rule has an exception?

substantial: "it MAY also define a coordinate system that can be used to interpret these measurements" Is there a controlled vocabulary for these? Everywhere that there's something that looks like there could be one (e.g. whenever something has a "type" this should be indicated).

substantial: Does ma:format include media type parameters?

ed.: In general it would be helpful if you could be clearer about what the normative statements apply to. What is it that MUST do this or that? Is it an abstract usage of an ontology? A concrete implementation? Something else?

ed.: It might be worth removing the XPath column from the tables when it's not used, that would save some horizontal scrolling.

ed.: Providing an explanation of the columns in the mapping table would be useful for people who weren't part of the group to figure out what exactly they are intended to convey.

substantial: There is no consistency in how XPath is used. Some expressions start with an element name, others with ./ without indications of what they are relative to. Some are rooted off a document. It is unclear when a namespace may or may not be involved. The TVA one gives a "Base" that is itself unrooted, and then goes on to say that each "term" should be preceded by the "namespace 'tva:'". I don't know what a "term" is, is it elements, attributes, the whole path? It would be clearer to use the prefix in the expression itself, where it belongs. And "tva:" isn't a namespace, it's a prefix that presumably maps to the TVA namespace — that namespace needs to be specified. In general it would be helpful if you reviewed your usage of XPath to make sure that each expression is correctly provided a namespace context matching the prefixes it uses, and is given an element or document context in which it can be evaluated. I'm not sure that the table heading is the best place for that (as done in the TVA section), I'd suggest simply explaining it right before the table. Being clear as to which version of XPath is intended would be helpful, especially since I see some "+" characters in some paths that I don't know how to interpret. In some cases it looks like you actually want something more powerful than what XPath can express — it's worth clarifying what you mean rather than resorting to shorthand for those.

ed.: Section 5 Conformance Requirements is a repeat of content that appears previously.

(space separated ids)
(Please make sure the resolution is adapted for public consumption)

Developed and maintained by Dominique Hazaël-Massieux (dom@w3.org).
$Id: 2418.html,v 1.1 2017/08/11 06:46:15 dom Exp $
Please send bug reports and request for enhancements to w3t-sys.org