XML versioned schema Project

Description

A project to ensure that DDCI's XML files refer to version specific XSD files.

Rationale

Currently most tools do not install XSDs for past tool versions. If someone makes an error when editing such an XML file, the upconvert logic can cause hard to diagnose issues. Having an XSD for the old schema enables the tool to diagnose the error in context.

An XML file with an old schema does not provide online help, or provides incorrect help in XSD aware editors like OpenArbor. This problem won't disappear until all XML files reference versioned XSDs.

Proposal

Tool updates

1. XML tools install versioned XSD files for recent schemas. The XSD filename shoud be of the form:

   schema-name-version.xsd

   For example: ddci:/xsd/vfileconfig-1.10.xsd

   1. Versioned XSD files should be created for schemas that are recent enough the tool is likely to encounter them.
   2. XSD files can be installed by adding the following to a component makefile.mk

      DI_DESK_ETC_XSD += vfileconfig-1.10.xsd

   3. If the tool DOES NOT have a toolVersion attribute, then the last unversioned schema should remain installed, and contain the content current when the tool was updated to have versioned schemas.
   4. When installing a config tool, install old schema versions:

      ...

      DI_DESK_ETC_XSD +=vfileconfig-1.9.xsd

      DI_DESK_ETC_XSD +=vfileconfig-1.10.xsd

      DI_DESK_ETC_XSD +=vfileconfig-1.11.xsd

The toolVersion attribute is (currently) required by the xml-tools-common infrastructure. It is not specifically required for doing versioned schemas. The current DDCI xml parser will use the toolVersion to guess the XSD version if the XSD URI does not contain a version, but it is MUCH preferred for XML files to specify a versioned XSD URI.

XML file updates

XML files that are instances of a versioned schema, e.g., /desk/etc/gmon.vfile.xml, should reference the XSD using a version specific URI. For example: ddci:/xsd/kfs-1.0.xsd, specifically the "-1.0".

Here is an example that uses a namespace:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<kfs xmlns="http://www.ddci.com/options"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://www.ddci.com/options http://www.ddci.com/xsd/kfs-1.0.xsd">

And for no namespace:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<vfileConfig
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:noNamespaceSchemaLocation="ddci:/xsd/vfileconfig-1.11.xsd">

Note: xml-tools-common currently requires a toolVersion attribute to facilitate upconvert.

Rationale: XML declaration for version, encoding, and standalone are all the default values. Its not clear these are needed, and the web guidance is mixed. Specifying them all is conservative. See https://www.w3.org/TR/xml/#sec-prolog-dtd

Status

Tasks

1. Update components to install versioned schemas.
2. Update tools that generate XML instance files to generate those files to reference versioned schemas.
3. Update components that have XML instance files to reference versioned schemas.
4. Update build-utils to warn if a component installs XML containing an unversioned XSD reference, when there are versioned XSDs for that reference.
5. Update build-utils to warn if a component installs an unversioned XSD unless there are versioned XSDs for that particular XSD.

   Rationale: The warning reminds component developers to continue to make progress and long term provide conformance guidance.

6. Update build-utils to validate installed XML files against their schema.