Versioning Allowed Value Sets

Background

Each of XML messages is defined by an XML Schema Definition (XSD) file. These files provide the structure of the messages defined in the relevant standard. These “message XSD” files then import a further XSD file that defines all the allowed value sets and allowed values that are used by that standard (“AVS XSD”). This allows DDEX to update the allowed value sets without also updating the standard itself.

When DDEX was founded in 2006, all standards used a common AVS XSD file with all standards’ allowed value sets. For a variety of reasons this policy was abandoned later, and most standards had their own AVS XSD file.

Going back to having one XSD file for all standards

In 2020, DDEX agreed to return back to the original approach. However, in addition to the old requirements that

  1. All XML standards should reference the same XSD file containing all AVSs/AVs and that

  2. It must be possible to update the AVS XSD used by a standard after the standard has been published, 

  3. It also needs to be possible to indicate which version of the AVS XSD is being used.

Version of the AVS XSD

The header of the AVS XSD file will now carry a version number in an annotation/documentation tag with the source being identified as “ddex:AvsVersionId”. Each time the file is updated, the version number will be increased. The current version is published here. 

Below is the header for the AVS XSD in version 5.

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:avs="http://ddex.net/xml/allowed-value-sets"
    targetNamespace="http://ddex.net/xml/allowed-value-sets"
    elementFormDefault="unqualified"
    attributeFormDefault="unqualified">
 
    <xs:annotation>
        <xs:documentation>© 2006-2021 Digital Data Exchange, LLC (DDEX)</xs:documentation>
        <xs:documentation>This XML Schema Definition file is […]</xs:documentation>
        <xs:documentation source="ddex:AvsVersionId">5</xs:documentation>
    </xs:annotation>

Location of the AVS XSD

The latest AVS XSD file will be published at: http://ddex.net/xml/allowed-value-sets/allowed-value-sets.xsd.

All old AVS XSD files will remain available at the following address: http://ddex.net/xml/allowed-value-sets/allowed-value-sets_vvv.xsd with vvv being the zero-padded version number.

Changes to the XML messages

All XML messages published in 2021 or later will carry a mandatory AvsVersionId attribute in the root tag. To indicate that the message sender has used version 5 of the AVS, the following XML header needs to be used (using the forthcoming ERN 4.3 message as the example):

<?xml version="1.0" encoding="UTF-8"?>
<ern:NewReleaseMessage xmlns:ern="http://ddex.net/xml/ern/43"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://ddex.net/xml/ern/43 http://ddex.net/xml/ern/43/release-notification.xsd"
     AvsVersion="5"
     LanguageAndScriptCode="en">

Changes to the processing of DDEX messages

To create a message that uses the latest XSD is not different from how things worked in standards published before 2021 – with the exception that the sender of a DDEX message needs to

  1. Obtain the version number of the latest AVS XSD and

  2. Include that in the AvsVersionId attribute as shown above.

If the message sender wants to signal that they only use allowed values from an older AVS XSD file, they simply need to use that file’s version number.
When receiving a message, a company can check the version number listed in the AvsVersionId attribute and compare it with the version it can support. Only if the AvsVersionId value from the message is the higher value, might there be an issue. However, this issue is not different to the situation before DDEX introduced the AvsVersionId attribute, as DDEX regularly updated its AVS XSD file(s).

XSD validation with an older AVS XSD file

If a company wants to technically validate a message with an older AVS XSD file, they need to

  • Download the relevant message XSD file and store it locally (e.g. in the same folder as the XML message to be validated);

  • Change, in that message XSD file, the pointer to the AVS XSD file in the import tag from http://ddex.net/xml/allowed-value-sets/allowed-value-sets.xsd to http://ddex.net/xml/allowed-value-sets/allowed-value-sets_007.xsd” (for version 7);

  • Change, in XML file to be validated, the location of the relevant XSD file by changing the schemaLocation attribute from, for example, http://ddex.net/xml/ern/43/release-notification.xsd to file:release-notification.xsd; and

  • Validate the XML message normally.

Search