Schema versioning policy

[thclark]

Pinned Note: Schema publication and change management

The schema is published online:

• Whilst in review, the candidate schema (with associated examples, tests and resources) is available on GitHub at https://github.com/octue/power-curve-schema/releases.
• On final release, the schema will be published to a permanent online repository.

The nature of data is to evolve rapidly, while revisions of IEC standards are periodic (typically over several years). To account for this dichotomy, revisions of the schema will be released conforming to the practice of Semantic Versioning.

In this practice, publication of the schema comprises a series of releases, each with a tag (e.g. 1.0.0) containing an optional candidate suffix (e.g. 1.0.0.alpha-1). The numbering in the tag conveys meaning as to the backward-compatibility and nature of changes between releases:

• A ‘major’ change (e.g. 1.0.0 to 2.0.0) indicates that the release contains a breaking change - in the context of JSONSchema, this means that it is possible for data which validated against the old schema may no longer validate against the new.
• The major change number will correspond with the standard edition; i.e. backward compatibility is maintained for a given edition. Breaking changes may occur between editions of the standard.
• A minor change (e.g. 1.0.0 to 1.1.0) indicates that the release contains a new property (or similar). This instructs the data provider in how to provide additional optional data (enabling new properties as evolutions in the industry occur and extra requirements emerge). Any such addition is optional (meaning that downstream consumers must not rely on its presence / must handle its absence).
• A patch change (e.g. 1.0.0 to 1.0.1) means no functional change - for example clarification of titles, comments or descriptions or a refactoring of the schema (having the same function but coded in a different way).
• A candidate change (e.g. 1.0.0.alpha-1 to 1.0.0.alpha-2) indicates a proposed release. If using candidate versions, data providers and consumers must specify the precise full version, since release content is subject to change (e.g. during IEC Committee Draft and subsequent stages) between candidates.

Adoption of this system allows data providers to provide additional optional data where minor revisions allow it, whilst forcing backward compatibility for all versions corresponding to a given edition number.