Versioning Patterns

Standards change: as a result versioning is an important part of many standards. This section documents common versioning patterns.

Normative and non-normative content

Problem

Some elements of a standards' documentation can be changed without changing what the standard means. Other elements may have consequences that may substantially affect data owners and users - and which should be subject to a governance and review process.

Solution

Clearly separate normative and non-normative sections of documentation.

Normative sections contain rules that an implementer of the standard MUST follow.

Non-normative sections contain explanation, guidance and context that MAY be useful to implementers, but is not binding for adoption of the standard.

The IETF use the distinction between normative and informative

Version numbers

Problem

Parsers, validators and other tools need to know what version of the schema a particular data file is using.

Solution

The package meta-data for any file should include a version field with a version number.

Example

From version 1.1, OCDS included a version field. This must contain only `MAJOR.MINOR' version (not 'MAJOR.MINOR.PATCH')

Release candidate versions

Problem

When a new version of a standard is released, and implementers start to use it, small problems are often discovered. These may require changes to the standard, sparking a whole new iteration of the governance process.

Solution

Major or minor versions of a standard may be provided as a 'Release Candidate' for a period of time, before, subject to no substantial changes being required, they can then be turned into a release version.

See release candidate (Wikipedia).