JourneyWeb
Versioning
JourneyWeb uses a systematic versioning scheme in line with >GovTalk & e-Gif< standards. This has the following elements.
- Version Numbering
- Version Location
- Version Identifiers
- 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