Draft 0.2 – open for comment. Changes are expected.

Give feedback

Versioning

How versions are numbered, what may change in which version and how fields are deprecated.

Version numbers

The specification uses semantic versioning: MAJOR.MINOR.PATCH. Records state the version they follow in specVersion as MAJOR.MINOR, for example 0.2; patch releases do not change specVersion. Schemas are published under a versioned path, for example /schemas/v0.2/core.schema.json, and are never changed in place once a version is released. Earlier drafts stay available under their own path.

Drafts before 1.0

Versions below 1.0 are drafts for comment. Fields, levels and code values can still change in incompatible ways between draft versions. Version 1.0 will be the first stable version.

From version 1.0

  • MAJOR – changes that can break existing records or data recipients: removing or renaming a field, raising a field from SHOULD or MAY to MUST, changing a type or a unit.
  • MINOR – additions that keep existing records valid: new optional fields, new blocks, new category profiles, new code values.
  • PATCH – clarifications of descriptions and corrections without effect on validation.

Deprecation

A field is marked as deprecated at least one minor version before it is removed. Deprecated fields carry the JSON Schema annotation "deprecated": true and a description of what replaces them. The changelog lists every deprecation.

Changelog

All changes are listed in the changelog.