Registry Versioning

RDF resources in the Registry must be immutable so that use of Registry URLs in logs and data structures across the Trust Framework do not change their meaning over time.

However, the Registry must be able to be changed. This specification defines a data structure to represent versioned resources within a Registry that change over time, with multiple linked versions, each of which has a separate URL.

RDF Prefixes

This specification uses the following prefixes:

  rdf:     http://www.w3.org/1999/02/22-rdf-syntax-ns#
  rdfs:    http://www.w3.org/2000/01/rdf-schema#
  ib1:     https://registry.trust.ib1.org/ns/1.0#
  xsd:     http://www.w3.org/2001/XMLSchema#

Versioned and unversioned resources

Not all resources in the Registry will be versioned. Resources which act as enumerations should not be versioned, as their URLs will be embedded into systems across the ecosystem, and cannot be easily changed. The Scheme must manage these unversioned resources in a backwards compatible manner.

All other RDF resources are versioned resources and include extra terms to manage change over time.

Structure

While the terms in Registry resources which describe the resource are immutable, Registry versioning adds additional terms which change over the lifecycle of a resource.

A Registry Change resource describes an atomic change to one or more resources in the Registry. It provides links to documents and other resources which describe the changes and the governance process. All Versioned resources link to the Registry Changes which affect them.

A versioned resource links to the previous and current versions to form a chain of versions.

To describe when a version of a versioned resource may be used, dates for availability for use, deprecation, and prohibition of use are added. When these dates are added or changed, an additional link to a Registry Change resource is added.

Version identifiers

Versioned resources include a version number in the URL and a version number term. This should be treated as an opaque identifier, but it is recommended that this identifier should be based on ISO8601 dates.

This also applies to text documents and OpenAPI definitions. When a file changes, the resources which refer to it also have a new version. However, to ensure downloaded files have a meaningful filename, the filename is of the format <filename>@<version>.<extension>#<digest>. The digest is an SHA-256 digest, to include a reference to the contents of the file in the RDF resources.

Versioning RDF terms

ib1:version (string): "Version number" of the resource, generally the date on which it was added to the Registry. Should be the last part of the URL.
ib1:availableFrom (xsd:date): Earliest time when this resource may be used.
ib1:deprecatedAfter (xsd:date): Latest time this resource may be used for new applications. Not present or in the future for the current version.
ib1:prohibitedAfter (xsd:date): May not be used after this time. ib1:deprecatedAfter must be set, with a datetime no later than this time.
ib1:hasCurrentVersion (URI): URL of the current version of this resource. Updated on all previous versions when publishing a new version. The current version must have a URL pointing to itself.
ib1:previousVersion (URI): URL of the previous version.
ib1:registryChange (URI): URL of an ib1:RegistryChange resource which explains why the Registry was changed. There may be more than one Registry Change value, to reflect creation of this version, creation of the next version, and deprecation and prohibition of use.

ib1:RegistryChange resource

To document the changes to the Registry and identify all resources which were changed in an update, all resources link to one or more ib1:RegistryChange objects.

Each change may only include changes from one scheme (or be scheme-less, making changes at the Trust Framework level).

ib1:RegistryChange resources have terms:

rdfs:label: Version number (usually date). By convention, all resources in this update should have the same version number.
rdfs:comment: Summary of change, suitable for displaying in a changelog.
ib1:trustFramework: URL of the Trust Framework.
ib1:scheme: URL of the Scheme, if applicable.
dcterms:references: URLs of documents which show evidence of the governance process. Where possible, these documents should be stored in the Registry.
ib1:registrySnapshot: URL of file which represents the state of the Registry at the point this change was made.
ib1:registrySnapshotSignature: Detached signature of the snapshot file, using a Directory issued certificate, as a PEM encoded signature with PEM encoded certificates appended. The snapshot file itself won’t contain this signature, but the following snapshot will. Snapshots are chained and entries can’t be added or removed.