img
Home > Candidate Patterns > Forwards Compatibility

Forwards Compatibility

How can a service be forwards compatible with service consumers?

Problem

Service consumers are unable to process documents generated by newer services because they have not been updated to understand new content.

Solution

Consumers must accept and either preserve or ignore unknown extensions using a space of identifiers that are compatible with the previous version.

Application

Messages exchanged by services can employ the addition of content using the language's extensibility features. Removal/retention of content can also be employed under certain circumstances.

Impacts

Service consumers must employ additional complexity within their service logic to handle the language extensions.

Architecture

Service

Status

Under Review

Contributors

David Orchard

Problem

Service consumers are often unable to support newer service providers because of expectations related to message definition. The challenge is to develop an interface and messages that are accepted by older service consumers

img

Solution

Services that employ forwards compatible changes mean that documents or messages produced by newer producers will be compatible with older consumers. Addition of content using a language's extensibility features is the most common forwards-compatible change. Removal of content can also be a forwards-compatible change under certain circumstances.

img

Application

The following two options provide forward compatibility:

  • Addition of Content/Versioning Identifiers via Language Extensibility
  • Removal/Retention of Content

Language Extensibility should be designed into the service contract. A common contract language is XML Schema, and it has support for some types of extensibility.

Extensibility in the contract must include a processing model that instructs what to do with unknown extensions. Typically this means to not generate a fault when unknown extensions are encountered. The following best practices should be employed:

  • Consumers must accept unknown extensions. Consumers must ignore unknown extensions; or consumers must accept and preserve unknown extensions.
  • Forwards compatible extensions must not change the meaning of existing components.

Finally, the future version identifiers that are compatible and should not cause faults within the system must be specified. A sample identification would be major versions are specified via the first number 1.X, 2.X etc. A minor version is the second number X.1, X.2 etc. An algorithm for indicating compatibility would be major versions are not compatible but minor versions are. For example 1.0 and 2.0 are not compatible whereas 1.0 and 1.1 are. An additional best practice around versioning is:

  • A consumer of a given major version must not fault on documents that have the same major version.

When accepting extensions, there is a decision as to whether to ignore or retain the content in question. When ignoring content the following options exist:

  • Ignore the entire sub-tree under the unknown extensions starting with the unknown element
  • Ignore the just the unknown element/attribute

When retaining the content the unknown extensions can be separated from the known content and forwarded/stored without processing.

Impacts

Forward compatibility presents challenges in the service consumer and provider. Both need to be aware of the messages that are exchanged by examining the version identifiers. Whether the information is accepted, preserved or discarded then needs to be executed based on the versioning and content that is present. This process adds significant complexity in the design of the service contract, Message processing logic/core service logic as well as the downstream service consumers and is likely to reduce the speed of composability of services employing forwards compatibility.