Skip to content
RUMLRUML

Open Format for Digital Law

2.3 Versioning

2.3 Versioning

Format Version vs. Content Version

RUML distinguishes two independent version levels:

LevelFieldDescriptionExample
Format version$specVersionVersion of the RUML specification“1.0”, “1.1”, “2.0”
Document versionmetadata.versionVersion of the content of this RUML file“2024.1.0”, “1.0.0”

Semantic Versioning for Format Version

The format version follows Semantic Versioning:

  • MAJOR: Incompatible changes (1.0 → 2.0)
  • MINOR: Backward-compatible extensions (1.0 → 1.1)
  • PATCH: Bug fixes in the specification (1.0.0 → 1.0.1)

Backward compatibility

Within a MAJOR version, new versions of the specification keep the schemas and the evaluation behavior backward-compatible: RUML files, RUML-Ext files and RUML Result files that are valid under one version stay valid under later MINOR and PATCH versions, and a RUML file evaluates, together with its RUML-Ext files, to the same result. Only a new MAJOR version can break this.

The $specVersion Field

The $specVersion field consists of MAJOR and MINOR only; a PATCH version bump does not change it. It defines the version of the specification the file conforms to. The schemas list the versions a file may declare, in the enum of $specVersion (Rule FMT-04FMT-04 $specVersion MUST be one of the versions listed in the enum of $specVersion in the schema.).

The version of a parser or evaluator is the highest version of the specification it implements.

Parser requirements:

  • A parser MUST accept a file whose $specVersion has its MAJOR version and a MINOR version up to its own (Rule FMT-09FMT-09 A parser MUST accept a file whose $specVersion has its own MAJOR version and a MINOR version up to its own, and MUST reject a file with a higher MINOR version or a different MAJOR version.).
  • A parser MUST reject a file whose $specVersion has a higher MINOR version or a different MAJOR version with a clear error message (Rule FMT-09FMT-09 A parser MUST accept a file whose $specVersion has its own MAJOR version and a MINOR version up to its own, and MUST reject a file with a higher MINOR version or a different MAJOR version.).

Evaluator requirements:

  • The input version of an evaluation is the highest $specVersion among the RUML file and its RUML-Ext files.
  • If the input version has an earlier MINOR version than their own, evaluators MUST produce the same result as an evaluator that implements the input version.
  • The result MUST have the input version as its $specVersion, not the evaluator’s version.