Version management and compatibility

During further development of this specification, not all involved implementations are expected to incorporate the specification's latest version. It is therefore necessary to ensure that servers and clients implementing different versions of the Veloconnect specification can interact as smoothly as possible. Further development of the specification must accordingly abide by the following rules:

Rule: Version guideline

1. Each Veloconnect specification is numbered according to the scheme {version}.{revision}, with {version} representing the version number, and {revision} representing the revision number. This specification therefore has version number 1 and revision number 3. A specification is newer than another if its version number is higher, or if the version numbers match and the revision number is higher.

2. Changing at most within a period of 12 months is the version number.

3. The namespaces of modules defined in the specification are all designated according to the scheme urn:Veloconnect:{module-name}-{version}.{revision}. The version number matches the specification's version number. The revision number corresponds to the last revision in which this module was added or modified.

4. A module used in a Veloconnect specification {version}.{r1} is also used in all specifications {version}.{r2}, if r2 is larger than or equal to r2.

5. A module's schematic definitions are modified as follows: Suppose D is an XML document valid according to specification u.v, and u.y is a more recent specification of the same version. We can transform D into an XML document E so as to replace the identifiers of namespaces with the associated identifiers of the newer specification assigned in the previous section. The transformed document E will then also be a valid document according to the specification u.y.

6. Suppose D is an XML document valid according to specification u.v, and x.y a newer specification where x and u are different. If transformation of namespaces for document E can be performed similarly to the previous case, and the root element of E is declared in the newer scheme, then document E is also valid according to specification x.y.

This rule implies extensive downward compatibility. It also demonstrates that implementations essentially use namespaces as a signal to identify the version of the specification according to which the involved parties are operating, and that a use of unqualified names does not lead to any misunderstandings.

 Requests in the URL(-S) binding lack information about namespaces. Introduced therefore for this binding with Veloconnect 1.3 was a parameter version allowing the client to communicate the version it supports.

 This can have various consequences for the client and server, if they communicate with a counterparty which implements a different version of the specification. Some recommendations are made for implementation of clients, some related rules are formulated for servers.

Recommendations for client implementations

• Implementation should not make assumptions about an absence of elements or attributes. It is thoroughly possible for a newer specification, for example, to insert another optional element between two child elements.

• Similarly, additional values may be allowed for types defined as enumeration. Implementation should be prepared for this case and, if necessary, generate a notice for the user.

• Because a server is not expected to implement the latest specification, it might be necessary to support outdated operations, i.e. those no longer provided for in the current specification.

Rule: Downward compatibility (server)

When dealing with clients which implement an earlier specification version, a Veloconnect compliant server must observe the following rules:

1. If a request from the client can be converted into a valid request via transformation of the namespaces described above, this transformed request must be answered in accordance with the specification.

2. Otherwise the server can choose whether the request is answered according to an earlier specification, or whether error code 406 is returned.

Rule: Upward compatibility (server)

 When dealing with clients which implement a later specification version, a Veloconnect-compliant server must follow the following rules

1. If a request from the client can be converted into a valid request via transformation of the namespaces, this transformed request must be answered in accordance with the specification.

2. Otherwise error code 405 is returned.