The GS1 XML suites of standards are published as major and minor versions. The minor versions are backward compatible.
Backward compatibility means that a message sender can create a business document based on an earlier schema and send it to a recipient, who can successfully validate it against a later schema.
The GS1 versioning uses three numbers to denote a change or update to the standards
N– used for major changes that are not backward compatible to earlier publications of XML standards
N.n – used for publication updates that are backward compatible within the same major release
N.n.n– used for minor changes: errata, navigation, document updates, new guidelines, etc., that are backward compatible within the same major release
Example
If the Order BMS 2.6.0 required a change to the common library that affected all messages, the new version was renamed Order BMS 3.0.0.
Minor versions
- Minor versions are interim releases of an XML schema that contain only the changes that are backwardly compatible with the existing version of this schema.
- The following changes can be incorporated in a minor version:
- Adding new optional elements or optional attributes
- Changing attributes cardinality from mandatory to optional
- Changing element multiplicity from old schema [0..1] to new schema [0..*]
- Changing element multiplicity from old schema [1..1] to new schema [1..*]
- Adding a value to an enumerated list
Major versions
Major versions are the releases of a suite of XML schemas that contain changes NOT backwardly compatible with the existing suite of the same schemas.
The following changes require incrementing the major version:
- Changing an attribute cardinality from optional to mandatory
- Adding a mandatory element
- Changing an attribute or element tag name
- Changing element multiplicity from old schema [0..*] to new schema [0..1]
- Changing element multiplicity from old schema [1..*] to new schema [1]
- Changing the sequence of elements in a <xsd:sequence>tag
Specifying version numbers
Specifying version numbers in the XML schema file
The major version number of the schema is specified in the schema namespace.
Example
urn:gs1: ecom: order:xsd:3
The minor versions are reflected in the version attribute of the <xsd:schema> element. For the ease of implementation, the internal schema version attribute reflects the entire version (both major & minor) of the schema.
Example
<xsd:schema version="3.0">
This approach ensures backward compatibility. Due to the fact that the minor versions are not reflected in the namespace of a schema, instance documents can be validated against the older minor version of the schema.
The full version number (major and minor) is also specified in the <xsd:annotation> element of the schema. This is a non-parsed piece of text containing information for the users.
Example
<xsd:annotation><xsd:documentation>
....
Version Information:
Version Number: 3.0
Date of creation: August 2011
....</xsd:annotation></xsd:documentation>
Specifying version numbers in the XML instance file
Since the major version is specified in the namespace, the business document (XML instance document) contains the major version by default. However, the complete version also needs to be specified in the instance document, as the application systems that receive the business documents need to know what version the trading partners are using.
The minor version is reflected in the optional ‘documentStructureVersion’ element. For the ease of implementation, it reflects the entire version (both major & minor) of the schema used as a base for creating this document. E.g. for the Order.xml message, the ‘documentStructureVersion’ reflects the version number of the Order.xsd schema.
Example
<documentStructureVersion>3.0</documentStructureVersion>
Specifying version numbers in the Standard Business Document Header
The Standard Business Document Header schema contains the 'TypeVersion' element, which is the placeholder for the version of the business document or business documents sent with the one header. The SBDH specification requires that all the documents sent with one header have the same version number.
To comply with this requirement, GS1 recommends that only business documents belonging to the same BMS publication release and having the same version number are included in the payload, if sending more than one document in the same message (see: Batching of business documents).
Publication of different schema versions
The minor versions of GS1 XML schemas are published as a part of a given major version of the standards. The next minor release always contains only these messages that have been changed in any way. All the other messages will remain the part of the previous minor release. It should be noted, however, that due to the backward compatibilty of the common components, there is no problem in using messages from different minor releases in the same message choreography, e.g. Order 3.0, Despatch Advice 3.2 and Invoice 3.5.
Note: The file names of the GS1 XML schemas do not contain version numbers, so e.g. both Order 3.0 and Order 3.1 will have the file name: Order.xsd.