Skip to content

#2 - Use Semantic Versioning

Versioning is essential for transparency, sustainability, and trust in semantic artefacts (SAs)(1). The ‹H/RADIOSA› initiative strongly recommends adopting Semantic Versioning (SemVer) as a standard practice.

  1. Semantic artefacts (SAs) comprise ontologies, thesauri, metadata standards, and any resources that sit at the crossroads of these categories. The term Heritage Semantic Artefact (HSA) is used here to denote those SAs that are specifically developed for the Heritage domain.

What Is Semantic Versioning?

Semantic Versioning (SemVer) is a system for numbering software releases so that each version conveys meaningful information.
The format is: MAJOR.MINOR.PATCH.

  • MAJOR – incompatible changes (e.g., removal or redefinition of concepts).
  • MINOR – backward-compatible additions (e.g., new classes or properties).
  • PATCH – backward-compatible fixes (e.g., typos, scope note refinements).

For example:
- 2.3.4 → Major = 2, Minor = 3, Patch = 4

Although originally designed for software, semantic artefacts should also be considered software-like resources, making SemVer highly relevant.

Why It Matters for Heritage Semantic Artefacts

The H-SeTIS survey showed that most heritage semantic artefacts lack structured versioning. This creates problems:

  • Users cannot easily track changes over time.
  • Breaking changes may disrupt dependent systems without warning.
  • Lack of provenance makes it difficult to evaluate trustworthiness.

How to Implement Versioning

Even when standards such as SKOS or RDFS lack native versioning support, best practices can be applied using widely adopted properties:

  • owl:versionIRI – persistent identifier for a specific version.
  • owl:versionInfo – human-readable version number (e.g., SemVer format).
  • owl:priorVersion, dcterms:hasVersion – links between versions.
  • Git-based repositories (GitHub, GitLab) – to track changes, manage releases, and publish changelogs.

Changelogs and Transparency

Version numbers alone are not enough. Developers should also maintain changelogs, which:

  • Record all modifications systematically.
  • Communicate the scope and impact of changes.
  • Help users decide whether to upgrade or adapt.

Changelogs are best managed in open repositories with issue tracking (e.g., GitHub Issues). This allows community members to follow discussions and understand the rationale behind changes.

Practical Example

Change Type SemVer Level
New classes/properties for new use cases MAJOR
Deprecation or removal of elements MAJOR
New single class/property (extends model) MINOR
Scope note or definition refinement PATCH
Typos, grammar fixes, small corrections PATCH

Recommendations

  • Always assign SemVer-style version numbers to semantic artefacts.
  • Use OWL versioning properties to embed version information.
  • Maintain public changelogs in Git repositories.
  • Signal backward-incompatible changes with a MAJOR version bump.
  • Engage with users via issue tracking to document discussions and decisions.