29

When it comes to documenting the structure of XML files...

One of my co-workers does it in a Word table.

Another pastes the elements into a Word document with comments like this:

<learningobject id="{Learning Object Id (same value as the loid tag)}" 
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                xsi:noNamespaceSchemaLocation="http://www.aicpcu.org/schemas/cms_lo.xsd">




<objectRoot>
    <v>
        <!-- Current version of the object from the repository. !-->
        <!-- (Occurance: 1) -->
    </v>
    <label>
        <!-- Name of the object from the repository. !-->
        <!-- (Occurance: 0 or 1 or Many) -->
    </label>
</objectRoot>

Which one of these methods is preferred? Is there a better way?

Are there other options that do not require third party Schema Documenter tools to update?

Travis
  • 2,105
  • 2
  • 26
  • 35
joe
  • 16,988
  • 36
  • 94
  • 131

6 Answers6

44

I'd write an XML Schema (XSD) file to define the structure of the XML document. xs:annotation and xs:documentation tags can be included to describe the elements. The XSD file can be transformed into documentation using XSLT stylesheets such as xs3p or tools such as XML Schema Documenter.

For an introduction to XML Schema see the XML Schools tutorial.

Here is your example, expressed as XML Schema with xs:annotation tags:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="objectroot">
    <xs:complexType>
      <xs:sequence>
        
        <xs:element name="v" type="xs:string">
          <xs:annotation>
            <xs:documentation>Current version of the object from the repository.</xs:documentation>
          </xs:annotation>
        </xs:element>

        <xs:element name="label" minOccurs="0" maxOccurs="unbounded" type="xs:string">
          <xs:annotation>
            <xs:documentation>Name of the object from the repository.</xs:documentation>
          </xs:annotation>
        </xs:element>
        
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>
Pux
  • 421
  • 3
  • 18
Phil Ross
  • 25,590
  • 9
  • 67
  • 77
  • Well played Phil, well played ;) – Adam Harte Nov 18 '09 at 03:47
  • Good idea. Although I am a little worried that my documentation will never get updated because someone now needs another tool to update it. – joe Nov 18 '09 at 04:56
  • 2
    @joe: an option is to use that file directly *as* the documentation - with the bonus that you can use standard tools to produce further documentation; and also use the XSD to to check (validate) the XML; and to exchange with other parties who might need to understand your format. Because it's a standard, learning to use it becomes a valuable skill for you in other tasks/employers - and similarly, it's a common skill in the employment pool, so replacements can be found. Unfortunately, it's an awful standard in that it's harder to read and write than either of your examples. – 13ren Nov 18 '09 at 05:59
  • @13ren: Yes, it is unfortunate that the structure of an XSD file is so hard to read. I would not feel comfortable passing it off as "documentation". It would be nice if there was a tool that could open an XSD file in a user friendly view. (As apposed to a tool that generates a readonly file for viewing). Or even a tool that generates a Word document version of the documentation would be nice. – joe Nov 18 '09 at 22:21
  • @joe: It may or may not fit your notion of user friendliness, but one tool that allows an XSD schema document to display in a Web browser is the [xsd.xsl](http://www.w3.org/2008/09/xsd.xsl) stylesheet on the W3C web site. It does not hide the XSD syntax or translate it into more legible forms, but it does display XHTML-encoded documentation elements nicely and it turns references to other components defined in the same schema document into hyperlinks (in any non-Mozilla browser). – C. M. Sperberg-McQueen Feb 02 '13 at 01:12
6

Enjoy RELAX NG compact syntax

Experimenting with various XML schema languages, I have found RELAX NG the best fit for most of the cases (reasoning at the end).

Requirements

  • Allow documenting XML document structure
  • Do it in readable form
  • Keep it simple for the author

Modified sample XML (doc.xml)

I have added one attribute, to illustrate also this type of structure in the documentation.

<objectRoot created="2015-05-06T20:46:56+02:00">
    <v>
        <!-- Current version of the object from the repository. !-->
        <!-- (Occurance: 1) -->
    </v>
    <label>
        <!-- Name of the object from the repository. !-->
        <!-- (Occurance: 0 or 1 or Many) -->
    </label>
</objectRoot>

Use RELAX NG Compact syntax with comments (schema.rnc)

RELAX NG allows describing sample XML structure in the following way:

start =

## Container for one object
element objectRoot {

    ## datetime of object creation
    attribute created { xsd:dateTime },

    ## Current version of the object from the repository
    ## Occurrence 1 is assumed by default
    element v {
        text
    },

    ## Name of the object from the repository
    ## Note: the occurrence is denoted by the "*" and means 0 or more
    element label {
        text
    }*
}

I think, it is very hard to beat the simplicity, keeping given level of expressiveness.

How to comment the structure

  • always place the comment before relevant element, not after it.
  • for readability, use one blank line before the comment block
  • use ## prefix, which is automatically translates into documentation element in other schema format. Single hash # translates into XML comment and not a documentation element.

  • multiple consecutive comments (as in the example) will turn into single multi-line documentation string within single element.

  • obvious fact: the inline XML comments in doc.xml are irrelevant, only what is in schema.rnc counts.

If XML Schema 1.0 is required, generate it (schema.xsd)

Assuming you have a (open sourced) tool called trang available, you may create an XML Schema file as follows:

$ trang schema.rnc schema.xsd

Resulting schema looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
  <xs:element name="objectRoot">
    <xs:annotation>
      <xs:documentation>Container for one object</xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="v"/>
        <xs:element minOccurs="0" maxOccurs="unbounded" ref="label"/>
      </xs:sequence>
      <xs:attribute name="created" use="required" type="xs:dateTime">
        <xs:annotation>
          <xs:documentation>datetime of object creation</xs:documentation>
        </xs:annotation>
      </xs:attribute>
    </xs:complexType>
  </xs:element>
  <xs:element name="v" type="xs:string">
    <xs:annotation>
      <xs:documentation>Current version of the object from the repository
Occurance 1 is assumed by default</xs:documentation>
    </xs:annotation>
  </xs:element>
  <xs:element name="label" type="xs:string">
    <xs:annotation>
      <xs:documentation>Name of the object from the repository
Note: the occurance is denoted by the "*" and means 0 or more</xs:documentation>
    </xs:annotation>
  </xs:element>
</xs:schema>

Now can your clients, insisting on using only XML Schema 1.0 use your XML document specification.

Validating doc.xml against schema.rnc

There are open source tools like jing and rnv supporting RELAX NG Compact syntax and working on both Linux as well as on MS Windows.

Note: those tools are rather old, but very stable. Read it as a sign of stability not as sign of being obsolete.

Using jing:

$ jing -c schema.rnc doc.xml

The -c is important, jing by default assumes RELAX NG in XML form.

Using rnv to check, the schema.rnc itself is valid:

$ rnv -c schema.rnc

and to validate doc.xml:

$ rnv schema.rnc doc.xml

rnv allows validating multiple documents at once:

$ rnv schema.rnc doc.xml otherdoc.xml anotherone.xml

RELAX NG Compact syntax - pros

  • very readable, even newbie should understand the text
  • easy to learn (RELAX NG comes with good tutorial, one can learn most of it within one day)
  • very flexible (despite the fact, it looks simple, it covers many situation, some of them cannot be even resolved by XML Schema 1.0).
  • some tools for converting into other formats (RELAX NG XML form, XML Schema 1.0, DTD, but even generation of sample XML document) exists.

RELAX NG limitations

  • multiplicity can be only "zero or one", "just one", "zero or more" or "one or more". (Multiplicity of small number of elements can be described by "stupid repetition" of "zero or one" definitions)
  • There are XML Schema 1.0 constructs, which cannot be described by RELAX NG.

Conclusions

For the requirement defined above, RELAX NG Compact syntax looks like the best fit. With RELAX NG you get both - human readable schema which is even usable for automated validation.

Existing limitations do not come into effect very often and can be in many cases resolved by comments or other means.

Jan Vlcinsky
  • 42,725
  • 12
  • 101
  • 98
  • 1
    This answer reads like a promotional ad for RELAX NG, takes up many times more space than the others (so much for 'Compact syntax') and still has to go through an xsd schema. In short, it obscures the other, better answers to the OP. – M.H. Jan 09 '20 at 14:45
  • @M.H. RELAX NG Compact syntax (RNC) does not require you to generate XSD at all. Comparing RNC to XSD from accepted answer it has the same number of lines and many time less characters. – Jan Vlcinsky Jan 13 '20 at 17:25
4

You might try documenting it by creating an XSD schema which would provide a more formal specification of your XML. Many tools will generate the XSD for you from sample XML as a starting point.

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="objectroot">
  <xs:complexType>
    <xs:sequence>
      <xs:element name="v" minOccurs="1" type="xs:string"/> <!-- current version -->
      <xs:element name="label" type="xs:string"/> <!-- object name -->
    </xs:sequence>
  </xs:complexType>
</xs:element>
</xs:schema>
zac
  • 961
  • 6
  • 11
  • Good idea. Although I am a little worried that my documentation will never get updated because someone now needs another tool to update it. – joe Nov 18 '09 at 04:56
  • @joe: You won't require a tool to maintain it. You can use something like XmlSpy to generate the XSD initially from your XML instance documents and then you can use notepad to maintain it going forward as they are just text documents. – zac Nov 18 '09 at 13:31
  • 1
    @zac: You do if you think of the overall process. (1) Someone reads documenation. (2) sees a change is needed. (3) Go back to the xsd source (4)Update the xsd source (5) Find tool such as XmlSpy to regenerate the documentation. having to get another tool is a burden and limits the use of this form of documentation. – joe Nov 18 '09 at 22:15
2

Personally, I would prefer seeing it in XML (the 2nd way).

Putting the elements in the table won't tell you clearly which elements are which elements' parent child and so on. Putting it in XML is rather clearer and I can see what's going on.

mauris
  • 42,982
  • 15
  • 99
  • 131
2

Showing it in a table has its limitaions e.g. mulit-levels of nested children, but for a simple XML structure I think this would be fine. For anything with more than one nested level I would prefer the XML way.

An even better way would be to create an XML Schema (XSD) file. That way, you get the benifits of seeing it in XML, and you can check the file after the data is inputted against the schema file using some software.

For a great series of tutorials on XSD check out w3schools - XML Schema Tutorial

Adam Harte
  • 10,369
  • 7
  • 52
  • 85
0

I just want to add one more thing, in case someone finds it useful.
I do sometimes programming in HTML and other times in android. When I do HTML I document my custom XML following the same format as W3Schools, as in http://www.w3schools.com/tags/att_a_href.asp if it is an android project I am working on then I follow Google standards as in http://developer.android.com/guide/topics/manifest/activity-element.html#screen
This way the programmers I work with do not have to do any extra work to understand my documentation.

Carolina Prieto Muñiz
  • 31
  • 3