Forwards- and Backwards-Compatibility
Forwards- and Backwards-Compatibility
This document is a guide on how to use the compatibility features of the PBS XML Schema.
The PBS XML Schema changes over time. The usual reason for change is to introduce new features, in order to implement new policies. Occasionally a change may be required to fix an issue. It is important to not adversely affect processing software when a change is introduced. For this reason the PBS XML Schema has facilities for managing backward- and forward-compatibility
The management of the PBS XML Schema is now starting with version 3.0. This is a major change from the previous version, 2.12. Major version changes are a fresh start; they are not compatible with any previous version.
Over time, new features will be need to be added to the schema. These will be added in a minor release of the schema, starting with version 3.1. Minor releases of the schema must be both backward- and forward-compatible.
"Backward-compatible" means that a processor that can accept a certain version of the schema can also accept earlier versions of the schema. For example, a processor that can accept a version 3.2 document can also accept a version 3.1 document.
A processor that is consuming historical PBS XML documents will need to be backward compatible with earlier versions of the schema.
"Forward-compatible" means that a processor that can accept a certain version of the schema can also accept a future version of the schema. For example, a processor that can accept a version 3.0 document can also accept a version 3.1 document.
For the PBS, forward-compatibility is an important feature to support since PBS XML documents are only produced from one source, the Department of Health. If the Department introduces new features in the PBS XML then processors that are consuming the current PBS XML will need to be forward compatible with the new version of the schema.
Forward compatibility is achieved using an extension layer. The extension layer is defined by the XML Namespace http://extension.schema.pbs.gov.au/. Elements in the PBS Namespace (http://schema.pbs.gov.au/) are never removed, their cardinality changed or the meaning of their content changed. New, minor versions of the schema always add new elements to the extension namespace.
In order to be forward-compatible, a processor MUST ignore elements in the extension namespace that it does not understand.
An extension element may be included in any complex PBS element (i.e. an element in the PBS namespace that allows element children in its content).
An example of an extension element is given below. In this example, the ext:form element has been added to the content of the ready-prepared element.
<prescribing-rule>
<ready-prepared>
...
<ext:form>eye ointment</ext:form>
...
</ready-prepared>
<code rdf:resource="http://pbs.gov.au/code/item">1002R</code>
</prescribing-rule>
Schema-validation of a PBS XML document is optional, since the Department of Health ensures that every PBS XML document is schema-valid upon publication. However, some recipients may wish to schema-validate a PBS XML document, for example to augment the document with the PSVI.
There are two modes for schema-validating a PBS XML document: forward-compatible or exact-version.
"forward-compatible" mode only validates elements in the PBS Namespace (http://schema.pbs.gov.au/). All elements in the Extension Namespace are ignored (i.e. they are always accepted as valid). To schema-validate a PBS XML document in forward-compatible mode use rng/pbs.rng (for Relax-NG validation) or xsd/pbs.xsd (for XSD validation).
"exact-version" mode validates all elements in both the PBS Namespace and Extension Namespace. This mode is specific to a particular minor version of the PBS XML Schema (i.e. version 3.1, version 3.2, and so on). To schema validate a PBS XML document in exact-version mode use rng/extension.rng (for Relax-NG validation) or xsd/extension.xsd (for XSD validation).
The PBS XML Schema is managed in such a manner as to always maintain backward compatibility. This is achieved by adhering to the following rules:
Elements are never removed.
Content is never removed from an element's content model. This includes changing the cardinality of elements in a content model.
The meaning of an element is never changed.
The data type of a simple content model is never changed.
The PBS XML Schema includes a forward compatibility mechanism. This allows the schema to be extended with new elements to provide new features. The forward compatibility mechanism works by separating new extension elements from existing elements using an XML Namespace. The XML Namespace URI for extension elements is http://extension.schema.pbs.gov.au/ and uses the prefix ext.
Every PBS element in the PBS XML Schema may be extended using a new element in the extension XML Namespace. There are no limits on the repeatability of extension elements, how many different extension elements may be included in a PBS element or the content of an extension element.
An important aspect of the forward compatibility mechanism is that an application must ignore extension elements that are not understood by the application. This allows an application to process a document that conforms to a newer version of the PBS XML Schema despite the presence of "foreign" elements.