Annotations in the LIXI XML Schema Definition (XSD) files

Overview

LIXI 2 Schema are now internally documented using annotation elements. Each Element, Attribute, Enumeration and Type within the schema have additional elements added within the annotation elements, demonstrated in the example below.

The data dictionary and schema documentation will be produced from the schema containing these annotations, with the source code of the schema and related tools being available in LIXI's GIT repository.

Rationale

This step is a part of a larger move for LIXI to enable greater levels of collaboration, generate higher quality documentation, improve usability, and improve the agility of schema development.

LIXI is changing the processes and toolsets used to manage our source code in GIT. As a result of moving the documentation into annotations within the schema, the documentation also becomes source code controlled. It is then easy to compare differences between any two versions, including the annotations and related documentation using the standard GIT toolset.

Many industry standard tools for visualising schemas or for auto-generating wrapper code for reading and writing XML are able to make use of any documentation within annotation elements in XSD files. LIXI is making it easier for our users to access this information within these standard tools by moving the documentation into the schema.

In addition, this will enable LIXI  to generate our schema documentation in HTML format and host it on the LIXI website, rather than distributing a monolithic PDF or XLS documents.

Finally, the tagging of elements for isolating individual transaction standards from the LIXI Master Schema is an important part of the plan for LIXI 2. There is a short video describing the new LIXI methodology for managing multiple standards within the LIXI Master Schema available here.

Example

<element name="ExampleElement">
  <annotation>
    <documentation> A human readable short definition of this 'ExampleElement'</documentation>
    <documentation> Further documentation, including hyperlinks, may be provided in subsequent documentation elements</documentation>
    <appinfo>
      <path>Sample.Demonstration.ExampleElement</path>
      <label>Example Element</label>
      <transactions>CAL,DAS</transactions>
    </appinfo>
  </annotation>
  <complexType>
  ... Sequences, Choices, Attributes etc in here
  </complexType>
</element>

Description of the Elements

  • The annotation element is simply a wrapper for all the documentation and appinfo content and is placed immediately under the item being described.
  • The first documentation element is for a short human readable definition of the item. This is typically displayed in schema visualisation tools.
  • The second and subsequent documentation elements can be used for further documentation including hyperlinks. These are typically ignored in schema visualisation tools.
  • The appinfo element a wrapper for some specific restricted content:
  • The path element shows one of two things: for an element or attribute that appears within an XML instance conforming to this XSD it shows a 'XPath-like' expression of the location of this item in that XML (using dot notation): for a common data type, it contains the name of the type. These are useful for uniquely identifying these items in an easy to read format.
  • The label element is used to provide a more readable version of the name of the element. In this case, the name is 'ExampleElement', whilst the label is 'Example Element' (notice the space in the label - whilst spaces cannot be used within an element's name).
  • The transactions element is used to explicitly declare which derived Transaction Schema will include this element (hence this element is only present in the LIXI Master Schema).

Updated: 25th February 2016