And given that you haven't introduced until here, the entire sentence seems problematic. Typically I'd expect someone to introduce briefly (one or two sentences) what something (MOCP) is before saying that it will be used. -> still no sentence introducing the MOCP, nor the lik with the Media Ontology, maybe adding "from the Media Ontology" would help? I don't think that we need a full 2 sentences to introduce the ontology and the properties as they are hyperlinked from this spot in the document. [cp] I removed the mentioning of MOCP at all (it is not used in the rest of the text). > vocabulary in the API. The description of relations between these > core properties and the metadata formats in scope (1.2 Formats > in scope) are stored in the Media Ontology in order to provide Does "Media Ontology" here refer to the same thing as MOCP earlier? if it does, then you should indicate that you intend to use that short form when you introduced it, if not, then you just used an undefined term. -> so indeed, we should add the MOCP from the Media Ontology, and link to the Media Ontology by a hyperlink at the first mention, otherwise it is indeed confusing. [CP] Media Ontology is removed from this sentence. > the goal to support interoperability between metadata formats. It offers change "to support" to "of supporting" -> "with the goal supporting interoperability" to be changed to "with the goal OF supporting interoperability" [CP] done > sources is handled by the user agent. Security considerations? -> I don't know whether security considerations were added to the document elsewhere? Maybe they could be mentioned here? [CP] We have a section on security considerations (section 7). However, I don't really get if these are applicable for this paragraph. > Scenario 2: Web service > The API is implemented as a Web service. Such an implementation would > be typically used by a non-UI client, such as an agent harvesting metadata. > However, the API could be also accessed from a user agent, and used the > same way as described in scenario 1 by the help of a JavaScript library for change "by" to "with" -> not done yet, but not sure whether it should be changed... [CP] In my version it is done... "used the same way as described in scenario 1 with the help of a JavaScript library fo..." > Overview of different API options. This alt text is woefully insufficient. It doesn't indicate that it's a diagram. -> add the mention that it's a diagram? [CP] The alt text now mentions that it is a diagram. > * An implementation of the API for Media Resource (as defined in this > document), which providers the actual getter methods for the properties. > * An implementation of the mappings from a specific source format to the > properties of the media ontology (as defined in Ontology for Media Resource 1.0). Why isn't "Media Ontology" written as a proper noun here? -> write "the Ontology for Media Resource 1.0." or "the Media Ontology", whichever is consistet with the rest of the document. [CP] Removed the Media Ontology. > * A format specific API to access the metadata. This can be an API for > accessing a metadata document describing a media resource (e.g. an XML > parser and a set of XPath statements) or an extractor to read metadata > embedded in the media resource (e.g. a library to read EXIF information from > JPEG images). > In order to define the context on which the API for Media Resource is working, change "on" to "with" -> changed but would it not be more relevant to write "in"? [CP]Changed to "in" > it is assumed that there is at least a unidirectional reference from the media why are you assuming things? -- this is an editorial complaint, the statement needs to be active "one needs at least ..." -> "In order to define the context with which this API is applied, at least a unidirectional reference from the media resource to the metadata document or vice versa." to be changed to "In order to define the context with which this API is applied, at least a unidirectional reference from the media resource to the metadata document or vice versa IS NEEDED." [CP] ok > Implementations of the API should provide objects implementing the different > interfaces. The entire description can be found in Appendix A. The API is > contained > within the MediaResource interface within the mawg module. > Objects implementing this interface provide the necessary methods to access > metadata properties of a Media Resource. The object holds methods to identify > the actual Media Resource and the metadata sources. All properties can be > accessed through a specific operation getProperty. ... specific operation: getProperty. -> even though there is a change of font, maybe the ":" would be a good idea indeed? [CP] There is a ":", what is the comment? > When an attempt to read a property fails, diagnostics information can be > obtained > using a diagnosis operation. Subtypes in the API are relevant for those > properties > mentioned in 4.1.3 Core properties of Ontology for Media Resource 1.0. > Lastly, methods are available that allow to iterate through the available > metadata. change "to iterate" to "iteration" -> not in the text anymore, so should be changed :) [CP]Indeed, this sentence has been dropped. > 3.1 MediaResource interface > The MediaResource interface offers a number of operations that allow > accessing the metadata of a Media Resource. ... provides a number of operations -> ok to access the metadata ... -> not done [CP]Ok changed I don't think that getProperty is a good name for something that might go into HTML DOM. -> changed to getMediaProperty, is it consistent with other places? [CP] It should be > interface MediaResource { > boolean selectMAResource (in DOMString mediaResource, in optional MetadataSource[] metadataSources); > MAObject[] getProperty (in DOMString propertyName, in optional DOMString fragment, in optional DOMString sourceFormat, in optional DOMString subtype, in optional DOMString language); getProperty is singular, it shouldn't be returning an array. Perhaps getMAProperties()? -> can't find it in the document. [CP] We answered that a singular method is best since only a single property is requested. > getDiagnosis > This operation allows to retrieve the status code(e.g., the getProperty > operation returning a null value). See Section 4 for details. I believe you should be using "function" or "method" instead of "operation" (global comment). -> still 51 "operation" in the document [CP] "Operation" is the term used in Web IDL to denote "method". And splitting a return value out of a function for the null case is not very DOMish, typically we'd use an Exception with the information in the exception object. Why aren't you? -> don't know whether this was changed [CP] We removed the "getDiagnosis" operation so it is no longer split. Exceptions are not used due to objections brought forward in comments to earlier drafts > requesting the creator results in MAObjects implementing the Creator interface > and so on. These interfaces are described in section 3.5 to 3.12. > propertyName DOMString ✘ ✘ > This argument identifies the property for which the values need to be > retrieved. > Optional arguments allow to refine the request replace "to refine" with "refining" and add a period to this "sentence" -> none of the two options in the document [CP]Sentence has been dropped > language DOMString ✘ ✔ > This argument allows to identify the language of the metadata. > Only if the metadata is available in the specified language, the values are > returned. Values for the metadata will only be returned if it is available in the specified language -> still 3 instances of the sentence to be changed in th document [CP]Ok, changed > 3.9.2.1 Attributes > link of type DOMString > This attribute holds a link to the license if it is externally available. Why is this a string instead of a url type? -> can't find the spot in the document the remark deals with [CP](section 3.13.2.1) Changed to "This attribute holds a URI, identifying the license if it is externally available." > codes for general informations (e.g., bad request), but also system specific information -> still one instance of informationS in the document, to be changed [CP]done