Documenting the Format of XML files

[Roedy Green]

Are there recommended formal ways of documenting the formats of XML
files? I don't just mean a validating schema, but something that
would let human understand how to compose the files?

 

[Stefan Ram]

Are there recommended formal ways of documenting the formats of XML
files? I don't just mean a validating schema, but something that
would let human understand how to compose the files?

A question on XML would be on-topic in comp.text.xml.

For an example of a specification of an XML application, see:

http://www.w3.org/TR/xhtml2/

 

[Oliver Wong]

Are there recommended formal ways of documenting the formats of XML
files? I don't just mean a validating schema, but something that
would let human understand how to compose the files?

[...]

For an example of a specification of an XML application, see:

http://www.w3.org/TR/xhtml2/

He asked for something that a *HUMAN* could understand. =P

Seriously though, whenever I've encountered good documentation for XML
file formats, they were usually in one of twoforms:

(1) a XSD schema with <!-- embedded comments --> describing each element
declaration and what they would be used for.
(2) an adhoc, plain text (or HTML) file describing each element and what
they would be used for.

- Oliver

 

[Real Gagnon]

Are there recommended formal ways of documenting the formats of XML

files? I don't just mean a validating schema, but something that
would let human understand how to compose the files?

One way is to use a style sheet to format as a treeview the XML data.

http://www.rgagnon.com/javadetails/java-0451.html

You see a sample at : http://www.rgagnon.com/examples/web2.xml
if your browser supports XML/XSL transformation (IE do, Netscape or FIrefox
don't).

Bye.

 

[Andy Dingley]

Are there recommended formal ways of documenting the formats of XML
files? I don't just mean a validating schema, but something that
would let human understand how to compose the files?

What's a "format" ? Just a Schema, structure and data typing? Or
something more, heading towards an ontology? You'll be using XML
Schema and possibly OWL too. Both of these have reasonable scope for
annotation metadata. Typically a simple XSLT stylesheet is used to
present these in a more human-friendly form.

You can also look at smart editors for these formats. Protege from
stanford.edu is well worth a look at it (also read the "ontology 101"
paper and the "Protege pizza tutorial" from Manchester)

 

[Domagoj Klepac]

Seriously though, whenever I've encountered good documentation for XML
file formats, they were usually in one of twoforms:

(1) a XSD schema with <!-- embedded comments --> describing each element
declaration and what they would be used for.
(2) an adhoc, plain text (or HTML) file describing each element and what
they would be used for.

I second that.
And the most convenient way to view XSD schema I found is to open it
in XMLSpy and use its Schema/WSDL graphic view. Makes good prints as
well.

Domchi