Add a sssom_version slot

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
 

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
+

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`.

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