Top Five Reasons to Document Your Schemas

Schema development is often an iterative process, and developers don’t typically start from scratch – XML Schemas, and, increasingly, JSON Schemas, are pieced together from existing documents or inherited from other teams. The ability to discern how schema components relate and analyze notes about development choices is infinitely helpful – but so often impossible due to lack of effective documentation.

Let’s take a look at some of the reasons documentation should be an integral part of your XSD, JSON, or other schema development.

Benefits of XSD Schema Documentation

Here are the top reasons you shouldn’t skip the documentation step for your next schema.

1. Enables easy communication among development team members.

Schema dev is often a collaborative process, and clear, concise documentation helps avoid confusion and increase productivity, as different developers work on different aspects of a schema or collection of schemas. Peer review is another process facilitated by clear documentation, allowing multiple experts to weigh in on the content model.

2. Allows quick assimilation of inherited projects.

This follows the point above closely. Code passed on from an acquired company or transitioned department always benefits from documentation. Even if the project originated at your organization, the original developer may no longer be available, or maybe development was assigned in pieces and no single individual knows the entire project.

Of course, few projects are comprised of schemas alone. For complete analysis of existing code, it’s useful to generate UML diagrams to document and easily visualize the project.

3. Centralizes information about imported or included schemas.

Rather than sorting through numerous documents to ascertain the relationships therein, schema documentation can include information about all related documents in a single, centralized location.

4. Allows non-technical stakeholders to understand and analyze schema definitions.

Because schema documentation is human-readable, it opens the door to collaboration with a wide array of subject matter experts who can understand and offer input during schema development and evolution.

5. Automated tools make it easy.

Really, there’s no excuse not to document your schemas when software makes the process easy. Let’s take a look at how you can do it with one such tool: XMLSpy.

XMLSpy provides completely customizable, yet fully comprehensive, schema documentation for XSD Schemas, JSON Schemas, and XBRL Taxonomy Schemas. Let’s take a look at how it works.

Generate XML Schema Documentation

The XMLSpy XML editor provides automatic documentation generation for XML Schemas, JSON Schemas, XBRL Taxonomy schemas – and even WSDL definitions – and the process works similarly for each. With the schema document open, select Generate Documentation from the Schema Design menu.

You have the option to use the built-in documentation template, or, if you have Altova StyleVision installed, you can design your own template with as much customization as you require. Then, choose whether to generate documentation in HTML, Word, RTF, or PDF. (Note: PDF generation requires that StyleVision is installed on the same machine.)

Other options let you define how images are handled, and finally, exactly which components and details are documented. Let’s look at the generated documentation for an XSD, and then I’ll show you the various options for documenting JSON and XBRL schemas.

Here is a snippet of HTML documentation for the Expense Report XSD included in the XMLSpy examples project.

Schema components are displayed graphically along with the corresponding source code, and hyperlinks make it easy to cross-reference details of related elements, attributes, and types.

Properties and facets are clearly shown for immediate analysis.

When components from other schemas have been included, then those schemas are also documented.

 Generate JSON Schema Documentation

The ongoing adoption of JSON Schema to apply data validation to JSON streams underscores the importance of documentation for this type of schema, as well.

JSON Schema documentation generation options are similar to those for XSD, but, of course, JSON-specific, with options to include details about properties, arrays, patterns, and so on.

XBRL Taxonomy Documentation

Now we get to XBRL Taxonomies, some of the most complex schemas in town. Documentation here is not only useful for taxonomy developers, but also for non-technical XBRL stakeholders such as accountants and other professionals on the financial side of the house.

Available in the XBRL menu of the XBRL Taxonomy Editor, the Generate Documentation command offers up the usual options, this time specific to XBRL components like Labels and Linkbases.

Whether you’re working with XSD, JSON, or XBRL Schemas, the benefits of documentation generation for visualizing, understanding, and communicating schema structure and relationships are many – and the fact that you can auto-generate documentation in XMLSpy in a few seconds removes any barriers to getting the job done.

If you’re not already a customer, you can try XMLSpy free for 30 days.