JourneyWeb

Versioning

JourneyWeb uses a systematic versioning scheme in line with >GovTalk & e-Gif< standards. This has the following elements.

  1. Version Numbering
  2. Version Location
  3. Version Identifiers
  4. Version Behaviour of Servers for Requests & Responses

1. Version Numbering

2.1 Version Number Format

All JourneyWeb schemas are have a version Identifier of the form N.Ma, where:

  • N indicates a Major release, e.g. "2.0". A major release is usually not strictly compatible with the previous release. That is, a document at level n+1 cannot be parsed by a client at level n.
  • M indicates a Minor release, e.g. "2.1". A minor release is compatible with the previous release, providing any new optional features added in the release are not used. That is, a document at level n.(n+1) can be parsed by a client at level n, provided it does not contain new optional features.
  • a indicates an Unapproved draft, e.g. "1.0a", "4.3a". A letter suffix indicates that the release is not yet officially approved or released. Unapproved drafts may be superceded by later drafts without ever being promoted to a full release.

2.2 Version Incrementation

Any material change or changes (i.e. other than changes to a comment) to a published schema must be reflected in a new schema version.

2. Version Location

2.1 Schema versions

JourneyWeb schema versions are always located at a specific, versioned URL. The URL has the general form:

  • //www.journeyweb.org.uk/schema/N.M/JourneyWeb.xsd

Examples.

Version 2.1 of JourneyWeb:

Draft of Version 3.0 of JourneyWeb:

2.2 Namespace versions

Note that the namespace used for JourneyWeb is not itself versioned, in line with GovTalk & e-Gif standards, thus:

<xs:schema targetNamespace="http://www.journeyweb.org.uk/schemas/"

2.3 The Current version

The official 'current' version of JourneyWeb may be referenced without a version number, for example:

  • /journeyweb/schema/JourneyWeb.xsd

Only one version of the JourneyWeb schema will be current at a time; different previous and new draft versions may exist concurrently.

2.3 Directory Structure

JourneyWeb artefacts are organised into a hierarchical directory structure relative to the root domain, in accordance with the e-GifI versioning system. For example the directory structure used is as follows:

//www.journeyweb.org.uk/
//www.journeyweb.org.uk/schema/
...
//www.journeyweb.org.uk/schema/2.1.1/
//www.journeyweb.org.uk/schema/2.1.1/JourneyWeb.xsd
//www.journeyweb.org.uk/schema/2.1.1/guide/
//www.journeyweb.org.uk/schema/2.1.1/guide/journeyWebSchemaGuide.doc
//www.journeyweb.org.uk/schema/3.0a/
//www.journeyweb.org.uk/schema/3.0a/JourneyWeb.xsd
//www.journeyweb.org.uk/schema/3.0a/errorHandling.xsd
//www.journeyweb.org.uk/schema/3.0a/guide
//www.journeyweb.org.uk/schema/3.0a/guide/JourneyWebSchemaGuide.pdf
  ....

3. Version Identifiers

3.1 Schema Version Identifiers

All JourneyWeb schema versions have a formal version identifier in the header element:

<xs: schema targetNamespace="http://www.journeyweb.org.uk/schemas/"
xmlns="http://www.journeyweb.org.uk/schemas/"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"
attributeFormDefault="unqualified"
version="3.0"
id="JourneyWeb">
...

3.2 Document Version Identifiers

All JourneyWeb request & response documents have a version identifier which must be populated by the implementation to indicate the schema level against which the document validates. It can be used to determine the version of a given request or response document.

<?xml version="1.0" encoding="UTF-8"?>
<JourneyWeb
xmlns="http://www.journeyweb.org.uk/schema/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.journeyweb.org.uk/schema/3.0/
Version="3.0">
<Request/>
...
<Request/>
</JourneyWeb>

3. Version Behaviour of Servers

3.1 Request and Response Version Levels

A server that supports the JourneyWeb protocol should respond to a request with a reply at the same schema level as indicated in the request document. If the schema level is not supported it should return a specific exception message reporting the error.

A JourneyWeb server may support multiple schema levels. Support for deprecated schema levels will be withdrawn after an agreed date.


Page last updated: 2013/03/25