MIWP-18 XML schema maintenance

Objective

To define a process for managing changes to XML schemas based on requirements defined in https://ies-svn.jrc.ec.europa.eu/attachments/download/374/20140114_Slides_MIG_AnnexISchemaUpdates.pptx

Overview

Managing the dependencies between the model, schema and software applications is very important. If the dependencies are not managed correctly, then version lock-in can occur. This may result in the inability to release bug-fixes or minor versions or upgrade versions of the schema without releasing version of the dependent models.
It is also important that modellers and schema developers understand the impact that changes to the model/schema will have on software applications and that the supporting documentation describes the changes sufficiently to allow software developers to implement changes efficiently.

This version controlling specification shall provide a simple versioning mechanism so that:
Given a version number MAJOR.MINOR.PATCH increment the:
  • MAJOR version when you make incompatible changes,
  • MINOR version when you add functionality in a backwards-compatible manner, and
  • PATCH version when you make backwards-compatible bug fixes.

Additional labels for pre-release schemas are available as extensions to the MAJOR.MINOR.PATCH format

Provisions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as follows:
  • SHALL or the terms "REQUIRED" or "MUST", mean that the definition is an absolute requirement of the specification.
  • SHALL NOT or the phrase "MUST NOT", mean that the definition is an absolute prohibition of the specification.
  • SHOULD or the adjective "RECOMMENDED", mean that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course.
  • SHOULD NOT or the phrase "NOT RECOMMENDED" mean that there may exist valid reasons in particular circumstances when the particular behaviour is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behaviour described with this label.Rules for versioning

Rules for versioning

1. A normal version number MUST take the form X.Y.Z where X, Y, and Z are non-negative integers, and MUST NOT contain leading zeroes.

X is the major version,
Y is the minor version, and
Z is the patch version.> Each element MUST increase numerically: 1.9.0 -> 1.10.0 -> 1.11.0.

2. Once a versioned schema has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version.

3. Major version zero (0.y.z) is for initial development. Anything may change at any time. The schema should not be considered stable.

4. Version 1.0.0 defines the production schema. The way in which the version number is incremented after this release is dependent on rules for how the specific type of schema changes.

5. Patch version Z (x.y.Z | x > 0) MUST be incremented if only backwards compatible bug fixes are introduced. A bug fix is defined as an internal change that fixes incorrect behaviour.

6. Minor version Y (x.Y.z | x > 0) MUST be incremented if new, backwards compatible functionality is introduced to the schema.

It MUST be incremented if any functionality is marked as deprecated.
It MAY be incremented if substantial new functionality or improvements are introduced. It MAY include patch level changes.
Patch version MUST be reset to 0 when minor version is incremented.

7. Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the schema.

It MAY include minor and patch level changes.
Patch and minor version MUST be reset to 0 when major version is incremented.

8. A Major version MAY not be backwards compatible with a previous Major version.

9. A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version.

Identifiers MUST comprise only ASCII alphanumerics and hyphen [0-9A-Za-z-].Numeric identifiers MUST NOT include leading zeroes.
Pre-release versions have a lower precedence than the associated normal version.
A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version.
Examples: 1.0.0-alpha, 1.0.0-alpha.rc1, 1.0.0-rc1, 1.0.0-x.7.z.92.

10. Precedence refers to how versions are compared to each other when ordered. Precedence MUST be calculated by separating the version into major, minor, patch and pre-release identifiers in that order.

Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: Major, minor, and patch versions are always compared numerically.

Example: 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1.

When major, minor, and patch are equal, a pre-release version has lower precedence than a normal version.

Example: 1.0.0-alpha < 1.0.0.

Precedence for two pre-release versions with the same major, minor, and patch version MUST be determined by comparing each dot separated identifier from left to right until a difference is found as follows:
  • Identifiers consisting of only digits are compared numerically and identifiers with letters or hyphens are compared lexically in ASCII sort order
  • Numeric identifiers always have lower precedence than non-numeric identifiers. A larger set of pre-release fields has a higher precedence than a smaller set, if all of the preceding identifiers are equal

Example: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0.

Deprecating functionality

Deprecating existing functionality is a normal part of development and is often required to make forward progress. When an entity within the schema is deprecated you should do two things:
  • Update your documentation to let users know about the change.
  • Issue a new minor release with the deprecation in place.
  • Before you completely remove the functionality in a new major release there should be at least one minor release that contains the deprecation so that users can smoothly transition to the new schema.

FAQ

1 How should I deal with revisions in the 0.y.z initial development phase?
The simplest thing to do is start your initial development release at 0.1.0 and then increment the minor version for each subsequent release.

2 If even the tiniest backwards incompatible changes to the schema require a major version bump, won't I end up at version 42.0.0 very rapidly?
This is a question of responsible development and foresight. Incompatible changes should not be introduced lightly. The cost that must be incurred to upgrade can be significant. Having to bump major versions to release incompatible changes means you'll think through the impact of your changes, and evaluate the cost/benefit ratio involved.

3 What do I do if I accidentally release a backwards incompatible change as a minor version?
As soon as you realise that you've broken the versioning policy, fix the problem and release a new minor version that corrects the problem and restores backwards compatibility. Even under this circumstance, it is unacceptable to modify versioned releases. If it's appropriate, document the offending version and inform your users of the problem so that they are aware of the offending version.

Annex A. Types of change

A.1 Examples of major version increments

The following are typical examples which require a major version increment to be applied:
  • Name of a feature, attribute or association role is changed.
  • A feature, attribute or association role is deleted.
  • Add a new attribute or association role with multiplicity of 1 or 1..*
  • Changing the multiplicity of an attribute or association role from 0..1 or 0..* to 1 or 1..*
  • Change or delete an existing enumerated value
  • Changing the sequence order of attributes and association roles in the schema
  • Change an attribute to make it voidable (i.e. nullable)
  • Changing the type of an attribute which requires transformation (e.g. string to DateType). Note if the change to type does not require transformation then this could be treated as a minor change.
  • Changing the coordinate reference system of the dataset or feature type

A.2 Examples of minor version increments

The following are typical examples which require a minor version increment to be applied:
  • A new feature
  • Add a new attribute or association role with multiplicity of 0..1 or 0..*
  • Alter the multiplicity of an attribute or association role from 0..1 to 0..*
  • Alter the multiplicity of an attribute or association role from 1 to 1..*
  • Add a new value to an enumeration
  • For database schema, addition types of minor version increments may include:
  • Add, alter or remove or not null constraints (???)
  • Add, alter or remove indexes
  • Alter length of a column

A.3 Examples of patch version increments

A patch version increment shall be applied only if the bug fixes are backwards compatible and fall within scope of the examples listed under minor version increments.
If the bug fixes are not backwards compatible then the change is a major version increment.

Normative References

  • OGC 06-135r11 Policy Directives for Writing and Publishing OGC Standards: TC Decisions
  • Semantic Versioning 2.0.0, http://semver.org/

Terms and Acronyms

Terms
Backwards Compatibility: Data is compatible with earlier versions of the schema. A backwards compatible schema allows you to validly transform existing data to/from the new version without modifying existing applications/software. Modifications to a system that do not allow backward compatibility are sometimes called "breaking changes”. Therefore, backward compatibility is important because it eliminates the need to start over when you upgrade to a new schema.

Versioning: Process of assigning either unique version names or unique version numbers to unique revisions of resources.

Acronymns
ASCII American Standard Code for Information Interchange
CSV Comma (colon) Separated Value
GML Geography Markup Language
SQL Structured Query Language
XML eXtensible Markup Language
__