How to document the structure of XML files

Question

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

One of my cooworkers does it in a Word table:

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

<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?

Answer 1

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.

Answer 2

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"&gt;
<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>

Answer 3

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

Answer 4

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"&gt;
  <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>