7 Implement a version management policy

Stian Soiland-Reyes edited this page Mar 12, 2016 · 14 revisions

Rule 7: Implement a version-management policy

Permalink URI: https://w3id.org/id-rules/7

Changes in data resources impact how they can be referenced and used. If you issue identifiers, document the change history for the resource (see also Rule 8), or version the identifier itself, or do both and document these.

Explicit versioning is recommended if prevailing use of an unversioned identifier results in “breaking changes” (e.g., a change in the hypothesized cause of a disease). However, if new information about the entity emerges slowly and the changes are “non-breaking”, it is reasonable to instead maintain a machine-actionable change history wherein the changes are also categorized.

Versioning and change history work well together, especially when multiple types of changes overlap. Even when previous records are removed, the URI should continue to resolve, but to a “tombstone” page (Rule 8).

A summary of versioning recommendations follows in Tables 2a and 2b below. The article Data publication consensus and controversies gives a more in-depth discussion of change management considerations.

If you version identifiers at the level of the individual record, you must version in the Local Resource Identifier after the dot per UniProt in Table 2a; this provides continuity in your site and also enables a single CURIE prefix to be used with any version, e.g.:


Recommendation for record-level versioning with URIs

Table 2a

(for clarity, LRI only is shown below)

Recommendation Example
Version information should follow after a dot P12345.3
Base resource must resolve (302 redirect) to most recent version P12345
Base resource should be deterministically convertible from version P12345.1 to P12345
Older versions must resolve P12345.1
Illegal or invalid version must produce an informative error message P12345.302
Link from older version to current version must be provided P12345.3
A list of all previous versions should be available P12345 (see ‘History’ tab)
Two versions (or dates) should be comparable http://www.uniprot.org/uniprot/P12345?version=*

Recommendation for database-release versioning with URIs

Table 2b

Recommendation: Versioning may be done in the namespace (and ideally prefix):

| Identifier type | Example | | -----|--------- | ------- | | URI | http://Jul2015.archive.ensembl.org/Mus_musculus/Gene/Summary?g=ENSMUSG00000033577 | | CURIE | ENSEMBL-2015-07-MUSG:ENSMUSG00000033577 |

This section was modified from the original to add headers in Table 2b.