Re: Review of XML Serialization (first part)

Thanks for the review!

I made so many, and such large, changes that I don't think the diff  
is helpful. But see:
	http://www.w3.org/2007/OWL/wiki/XML_Serialization

The Schema has been updated to exactly capture the syntax of  
abbreviated IRIs. It also constraints the document to one Prefix  
element per declared prefix.

On 6 Apr 2009, at 14:44, Rinke Hoekstra wrote:

> Hi,
>
> Here's my review of the XML Serialization. I only had a cursory  
> look at the XML schema itself, but I will have another more  
> thorough look once the abbreviation mechanism is in place.

It's there now.

> Some of my comments are wordsmithing, but as this part of our  
> specification is a bit controversial, I think we should tread very  
> carefully...

Indeed.

> Overall
> * Some parts of the texts read as a report on how the XML schema  
> was constructed. I don't think that's the right tone for this  
> document, and I suggest a more matter-of-fact description of the  
> schema itself.

This was included in response to requests for evidence that OWL/XML  
in fact corresponded to the FS. I moved it to an appendix.

> * The document is titled "XML Serialization", but the text  
> consistently uses "XML Syntax". I suggest to use the former  
> throughout, as it is less contentious.

Fixed.

> * Document links called [OWL 2 Specification] point to the  
> structural specification (in line with what the Profiles and Direct  
> Semantics documents do). The Document Overview calls these links  
> [OWL 2 Structural Specification]... maybe consistent use of these  
> should be checked across all documents.

Deferred to the global rationalization of these references.

> Section 1 (Overview)
>
> * The section could use a bit more structure, e.g. by adding small  
> headings for paragraphs on mapping to UML classes, namespace,  
> parsing and profiles.

Agreed. It's become a catchall. I restructured the document. Please  
look again.

> 1st paragraph,
> * "RDF/XML remains the primary", consider rephrasing to "RDF/XML is  
> the primary" (current wording suggests that XML is somehow newer,  
> and we all know newer is better...)
> * the 'this' in "use of this syntax by OWL 2 tools is optional" is  
> a bit ambiguous.
> * 'link' to [XQuery] is not a link

Fixed to:
""" Although the XML serialization is designed as an
exchange syntax for OWL 2, RDF/XML is the only required exchange syntax
for OWL---use of the XML serialization by OWL 2 tools is optional.
"""

> 3rd paragraph
> * `links' to [OWL 2 Specification] and [XML Schema] are not links

Fixing (not yet fixed)

> * "The XML schema has been obtained by a straightforward  
> translation... " consider rephrasing to "The XML schema is a  
> straightforward translation..."
> * I had to look up the term 'eponymous' (as I had no clue as to  
> what it means), and it seems that it is more appropriately used to  
> refer to person names, rather than UML classes.

You spoil my fun. Fixed to:
"""Each such element has an XML Schema type with the same name."""

> 4th paragraph
> * What 'useful parents' are is not immediately obvious. (don't  
> think this needs a change in the doc...)

Yeah. Judgement call. Not worth documenting I think.

> 5th paragraph (starting with 'Additionally ..')
> * the "just didn't make sense" is a bit informal for a document.  
> Consider rephrasing to ".... some groups are mere documentation,  
> and are not included as types:"

Done.

> 7th paragraph
> * "Tools parsing OWL 2 ontologies in this syntax need to  
> additionally implement these global conditions", shouldn't/musn't  
> there be a should or must in this sentence?

See:
    http://www.w3.org/2007/OWL/wiki/XML_Serialization#Global_Constraints

> 8th paragraph
> * "Therefore the OWL 2 XML Syntax can be parsed more easily than by  
> using the canonical parsing process..." s/Syntax/Serialization, but  
> also "easily" is a bit too easy, consider a less informal word.

Fixed to:
"""Each axiom in the XML syntax of OWL 2 contains complete  
information about the type of all the entities in it. Therefore the  
OWL 2 XML Syntax parsing process is simpler than the canonical  
parsing process from Section 3.6 of OWL 2 Specification [OWL 2  
Specification]."""

> 9th paragraph
> * Text mentions "xsd:anyURI" but only refers to XML Schema part 1  
> (structure) and not part 2 (datatypes), consider adding a link to  
> http://www.w3.org/TR/xmlschema-2/

Fixing references.

> * What about the "owl:Prefix" element? It is defined by the schema,  
> but referred to anywhere else in the document. This section should  
> at least describe (or refer to) the way in which prefixed names are  
> resolved to full iri's

Please see:
    http://www.w3.org/2007/OWL/wiki/XML_Serialization#IRIs
>
> Section 2 (Example Ontology)
>
> * Is the reference to 'live-from-wiki.xsd" in the schema location  
> intentional? I assume the schema will change to a more permanent  
> location in the future. Perhaps we should use that location instead  
> of the live one?
> * Very (very) minor remark: class names usually start with an  
> uppercase character.

What classes?

> Section 3 (Example Ontology)
>
> Review is done *before* IRI abbreviation was introduced, but  
> *after* the Prefix element was defined.
>
> * The schema does not define the owl:priorVersion,  
> owl:backwardCompatibleWith and owl:incompatibleWith ontology  
> properties which are part of the OWL 2 Specification

The schema does not define any properties or classes (e.g.,  
owl:Thing). One just uses the appropriate IRIs in the right places.  
Did you have something else in mind?

I'm still cleaning up references and some wordsmithing/formatting. I  
will add some Prefixes to the example as well.

Cheers,
Bijan.

Received on Monday, 6 April 2009 19:14:32 UTC