diff --git a/CHANGELOG.md b/CHANGELOG.md index 3cc2b3b9..b7b419b2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,7 @@ - Add `composed entity expression` as a new value in the `EntityType` enumeration ([issue](https://github.com/mapping-commons/sssom/issues/402)). - Add `predicate_type` slot (previously defined but unused) to the `Mapping` and `MappingSet` classes ([issue](https://github.com/mapping-commons/sssom/issues/404)). - Add `similarity_measure` slot to the `MappingSet` class ([issue](https://github.com/mapping-commons/sssom/issues/411)). +- Add `sssom_version` slot to the `MappingSet` class ([issue](https://github.com/mapping-commons/sssom/issues/439)). - Change the type of the `see_also` slot to `xsd:anyURI` ([issue](https://github.com/mapping-commons/sssom/issues/422)). - TBD diff --git a/examples/schema/version.sssom.tsv b/examples/schema/version.sssom.tsv new file mode 100644 index 00000000..e4081653 --- /dev/null +++ b/examples/schema/version.sssom.tsv @@ -0,0 +1,9 @@ +# sssom_version: "1.1" +# curie_map: +# HP: http://purl.obolibrary.org/obo/FBbt_ +# MP: http://purl.obolibrary.org/obo/UBERON_ +# license: https://w3id.org/sssom/license/unspecified +subject_id predicate_id object_id mapping_justification +HP:0009124 skos:exactMatch MP:0000003 semapv:LexicalMatching +HP:0008551 skos:exactMatch MP:0000018 semapv:LexicalMatching + diff --git a/src/docs/spec-model.md b/src/docs/spec-model.md index 6171a91e..e9342d3b 100644 --- a/src/docs/spec-model.md +++ b/src/docs/spec-model.md @@ -192,3 +192,47 @@ If a defined extension slot has a `type_hint` other than `http://www.w3.org/2001 | http://www.w3.org/2001/XMLSchema#datetime | Implementations MAY check that the value is a date and time value in the ISO 8601 format (`yyyy-mm-ddThh:mm:ssTZ`) | Implementations MAY decide to recognise more types and to enforce type-specific constraints. For example, an implementation could recognise the type `http://www.w3.org/2001/XMLSchema#negativeInteger` and check that the value starts with a minus sign. + +## Versioning + +Starting from version 1.1 of the specification, the `MappingSet` class has an optional slot named `sssom_version` which indicates the version of the specification that the set declares itself to be compliant with. + +### Versioning rules + +The SSSOM specification mostly follows the [Semantic Versioning principles](https://semver.org/), but only version numbers with two components: a _major_ number _X_ and a _minor_ number _Y_, expressed as `X.Y`. + +A set that is compliant with a minor version _X.Y_ is also compliant with any minor version _X.Y+n_, for any value of _n_. The opposite is not true: a set compliant with a minor version _X.Y_ may not necessarily be compliant with a minor version _X.Y-n_. + +A set that is compliant with a major version _X_ may not be compliant with any other major version _X+n_ or _X-n_. + +Therefore, an implementation that is itself compliant with version _X.Y_ SHOULD always accept a set compliant with any version _X.Y-n_. It MAY reject outright a set compliant with any version _X.Y+n_ (more recent minor version), _X-n_ (older major version), or _X+n_ (more recent major version). + +In other words, the SSSOM specification guarantees backwards compatibility between two versions (in that a set compliant with an older version can be used with an implementation compliant with a newer version) only insofar as only the _minor_ version has changed. + +### Using the `sssom_version` slot + +When reading a SSSOM set: + +(A) If the set contains a `sssom_version` slot, implementations SHOULD check whether they recognize the indicated version as a supported version according to the rules in the previous section; if they don’t, they MAY reject the set outright. + +(B) If the set does not contain a `sssom_version` slot, it MUST be assumed to be compliant with version 1.0. + +When generating a SSSOM mapping set: + +(A) If the set uses slots or enum values that were added in more recent versions than 1.0, then the `sssom_version` slot MUST be set to the lowest version that defines all the slots effectively used. + +(B) If the set only uses slots or values that already existed in version 1.0, then the set is effectively compliant with said version 1.0 and the `sssom_version` slot MAY be omitted entirely. + +Note that, if the `sssom_version` slot is _not_ omitted, then it MUST be set to `1.1`, since that slot itself has been added in version 1.1. It follows that a `sssom_version=1.0` slot (a set that would declare itself to be compliant with version 1.0) is self-contradictory. + +### Model changes across versions + +For all slots that were added to the specification after version 1.0, the LinkML model contains an `added_in` annotation that indicates the exact version in which the slot was introduced. + +Not all changes can be annotated thusly in the LinkML model, though. For changes other than the complete addition of a new slot, implementation can refer to the following subsections. + +#### Model changes in version 1.1 + +* The `similarity_measure` slot, which previously only existed on the `Mapping` class, has been added to the `MappingSet` class. +* The value `composed entity expression` has been added to the `EntityType` enumeration. +* The type of the `see_also` slot has been changed to `xsd:anyURI`. diff --git a/src/sssom_schema/schema/sssom_schema.yaml b/src/sssom_schema/schema/sssom_schema.yaml index 42ed9462..da97a319 100644 --- a/src/sssom_schema/schema/sssom_schema.yaml +++ b/src/sssom_schema/schema/sssom_schema.yaml @@ -25,6 +25,10 @@ default_prefix: sssom default_range: string enums: + sssom_version_enum: + permissible_values: + "1.0": SSSOM specification version 1.0 + "1.1": SSSOM specification version 1.1 entity_type_enum: permissible_values: owl class: @@ -88,6 +92,15 @@ slots: range: ncname prefix_url: range: uri + sssom_version: + description: The version of the SSSOM specification a mapping set is compliant with. + range: sssom_version_enum + instantiates: sssom:Versionable + annotations: + added_in: "1.1" + see_also: + - https://github.com/mapping-commons/sssom/issues/439 + - https://github.com/mapping-commons/sssom/blob/master/examples/schema/version.sssom.tsv curie_map: description: A dictionary that contains prefixes as keys and their URI expansions as values. range: prefix @@ -235,9 +248,12 @@ slots: see_also: - https://github.com/mapping-commons/sssom/issues/143 - https://github.com/mapping-commons/sssom/blob/master/examples/schema/predicate-types.sssom.tsv - instantiates: sssom:Propagatable + instantiates: + - sssom:Propagatable + - sssom:Versionable annotations: propagated: true + added_in: "1.1" examples: - value: owl:AnnotationProperty - value: owl:ObjectProperty @@ -735,6 +751,7 @@ classes: license: required: true slots: + - sssom_version - curie_map - mappings - mapping_set_id @@ -904,6 +921,15 @@ classes: description: Indicates whether a slot can be propagated from a mapping down to individual mappings. range: boolean + Versionable: + class_uri: sssom:Versionable + description: Metamodel extension class to manage slots that may not exist in + all versions of the model. + attributes: + added_in: + description: The version of the specification in which the slot was added. + If not specified, the slot must be assumed to have been added in version 1.0. + range: sssom_version_enum NoTermFound: class_uri: sssom:NoTermFound description: sssom:NoTermFound can be used in place of a subject_id or object_id