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.:
UniProt:P12345.3
→ http://www.uniprot.org/uniprot/P12345.3.
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=* |
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.
10 Simple rules for design, provision, and reuse of identifiers for web-based life science data by Julie McMurry, et al. is licensed under a Creative Commons Attribution 4.0 International License.
Based on a work at http://dx.doi.org/10.5281/zenodo.31765.
Adaptation from the original preprint to wiki format include typography modifications, changing citations to updated hyperlinks, splitting sections/paragraphs and moving tables/boxes. Modifications by Stian Soiland-Reyes, eScience lab, University of Manchester.