Embedded Schema Documentation

Scouting the path towards reusable documentation

Back in March of 2008 Drybridge Consulting presented a proposal to papiNet to provide schemas with embedded documentation. Drybridge has performed this process for several North American groups so, the process runs well. The degree to which the embedded schema form of documentation was useful to these groups should be reviewed. While my impression is that the schema with embedded documentation was not widely used this could be due to the ready availability of the printed form and insufficient PR on the availability. The Drybridge Facilitator, which is available as a web-based tool (as well as in a local hard-drive implementation) is used to perform the tasks associated with producing documentation of this type. I would classify the Drybridge Facilitator as an off-the-shelf SaaS (Software as a Service) product.

Moving beyond the question of, “How does papiNet migrate towards embedded schema documentation?”, let’s discuss some of the issues associated with producing embedded schema documentation.

1. papiNet currently has two types of documentation, the data dictionary and the message documentation (business-document documentation). It was originally thought there would be a tighter association between the documentation for the dictionary and the business-document documentation. This has not been the case. There would be, if papiNet decided to produce business-document documentation that included definitions for only the elements, attributes, and enumerations in the particular XML schema. While I believe this would be extremely useful, there has not been a call for this type of documentation. Bottom-line: The more formal business-document documentation can be separated from the process of printing the data dictionary permitting ‘word-processed’ business-document documentation and an embedded-schema documentation approach.
2. Embedding documentation into the schema will result in a schema that is larger and may not be suitable for use in a production environment. Documentation is embedded into a schema by associating xs:documentation and xs:annotation elements with the items that they refer to. Schema parsers will identify and disregard the documentation during the load process. Regardless of whether the additional processing imposes a significant load on a system I felt that the papiNet community would object to being forced to use a schema that is loaded with documentation information. Bottom-line: A version of the schema with embedded documentation and without embedded documentation is required. In my mind this indicates that documentation should exist outside the schema and then be inserted into the schema.
3. papiNet makes extensive use of enumerated lists. There is no way to directly associate a definition with an xs:enumeration item in an XSD. While there are workarounds for this issue they place an onerous burden on the schema editor and dramatically increase the size of the documentation produced. (Essentially, the enumerations would be listed in the definition for the owning-item. Unfortunately, this would result in enumerations showing whenever the item is used in a construct. Currently enumeration definitions only show for the parent data dictionary entry.) Bottom-line: Managing enumeration definitions would require a modification to XML Spy, use of the Drybridge Facilitator, or a relaxation of the expectations of papiNet.
4. The ISS tool links to the data-dictionary using hyper-text-links that have a naming intelligence built in. Documentation produced by XML Spy uses (what I would term) a unique-identifier approach when creating links. I use the same approach when producing the links in the Drybridge Investigator (which produces Schema Difference Analysis). This unique-identifier approach allows the documentation process to disregard the potential for name-collisions. Preventing name-collisions is extremely important. Bottom-line: Since there is no way to predict the unique-identifier that is associated with an element or attribute the link between the ISS tool and the data-dictionary will be lost.

I’ve entitled this email “Scouting the Path” because I believe that producing schema with embedded documentation information is something that should be pursued and I stand ready to help achieve this goal. Please feel free to contact me with any questions.