Model propagatable slots (#371)

Resolves [#305] - [x] `docs/` have been added/updated if necessary - [x] `make test` has been run locally - [ ] tests have been added/updated (not applicable) - [x] [CHANGELOG.md](https://github.com/mapping-commons/sssom/blob/master/CHANGELOG.md) has been updated. If you are proposing a change to the SSSOM metadata model, you must - [ ] provide a full, working and valid example in `examples/` (**not applicable**: no new example needed as the change only affects how some slots should be interpreted; it does not add or remove slots, nor does it change how the propagated slots are used) - [x] provide a link to the related GitHub issue in the `see_also` field of the linkml model - [ ] provide a link to a valid example in the `see_also` field of the linkml model (**not applicable**, same reason as above) This PR finalises the fix to #305, by explicitly specifying, directly within the LinkML model, which slots are considered “propagatable” (previously this was only informally described in the spec, since #368). This is done by: * adding a “metamodel extension class“ (`sssom:Propagatable`) with a single boolean-ranged attributed `propagated`; * amending the slots that must be considered propagatable by making them instantiate the `sssom:Propagatable` extension.
mapping-commons · Jul 19, 2024 · 0af8c6f · 0af8c6f
1 parent 7c55f8f
commit 0af8c6f
Show file tree

Hide file tree

Showing 3 changed files with 64 additions and 4 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,9 +2,16 @@
 
 ## Next
 
-- Add issue_tracker_item and issue_tracker [model elements](https://github.com/mapping-commons/sssom/pull/259).
+- Add the concept of "propagatable slots".
+
+## SSSOM version 0.15.1
+
 - Add recommendation to sort the keys in the YAML metadata block.
 
+## SSSOM version 0.15.0
+
+- Add issue_tracker_item and issue_tracker [model elements](https://github.com/mapping-commons/sssom/pull/259).
+
 ## SSSOM version 0.13.0
 
 - The necessity of the "canonical column ordering" was downgraded from MUST to SHOULD (https://github.com/mapping-commons/sssom/pull/285)

diff --git a/src/docs/spec-model.md b/src/docs/spec-model.md
@@ -30,7 +30,9 @@ As mentioned briefly above, there are two different types of slots in the `Mappi
 * slots that provide informations about the set itself;
 * slots that provide informations about all the mappings in the set.
 
-The latter are called “propagatable slots”. The propagatable slots are:
+The latter are called “propagatable slots”. In the LinkML model, they are marked with a `propagated` annotation whose value is set to `true`.
+
+For convenience, here is the current list of propagatable slots:
 
 * `mapping_date`,
 * `mapping_provider`,
@@ -47,8 +49,6 @@ The latter are called “propagatable slots”. The propagatable slots are:
 * `subject_source_version`,
 * `subject_type`.
 
-(In a future version of this specification, this information will be formally specified directly within the LinkML schema.)
-
 When a mapping set object has a value in one of its propagatable slots, this MUST be interpreted as if all mappings within the set had that same value in their corresponding slot. For example, if a set has the value _foo_ in its `mapping_tool` slot, all the mappings in that set MUST be treated as if they had the value _foo_ in their `mapping_tool` slot.
 
 This mechanism is intended as a convenience, so that a slot which has the same value for all mappings in a set can be specified only once at the level of the set rather than for each individual mapping.

diff --git a/src/sssom_schema/schema/sssom_schema.yaml b/src/sssom_schema/schema/sssom_schema.yaml
@@ -173,6 +173,9 @@ slots:
   subject_type:
     description: The type of entity that is being mapped.
     range: entity_type_enum
+    instantiates: sssom:Propagatable
+    annotations:
+      propagated: true
     examples:
       - value: owl:Class
   predicate_id:
@@ -283,6 +286,9 @@ slots:
   object_type:
     description: The type of entity that is being mapped.
     range: entity_type_enum
+    instantiates: sssom:Propagatable
+    annotations:
+      propagated: true
     examples:
       - value: owl:Class
   mapping_set_id:
@@ -363,6 +369,9 @@ slots:
   subject_source:
     description: URI of vocabulary or identifier source for the subject.
     range: EntityReference
+    instantiates: sssom:Propagatable
+    annotations:
+      propagated: true
     examples:
       - value: obo:mondo.owl
         description: A persistent OBO CURIE pointing to the latest version of the Mondo ontology.
@@ -371,6 +380,9 @@ slots:
   subject_source_version:
     description: Version IRI or version string of the source of the subject term.
     range: string
+    instantiates: sssom:Propagatable
+    annotations:
+      propagated: true
     examples:
       - value: http://purl.obolibrary.org/obo/mondo/releases/2021-01-30/mondo.owl
         description: (A persistent Version IRI pointing to the Mondo version '2021-01-30')
@@ -391,6 +403,9 @@ slots:
   object_source:
     description: URI of vocabulary or identifier source for the object.
     range: EntityReference
+    instantiates: sssom:Propagatable
+    annotations:
+      propagated: true
     examples:
       - value: obo:mondo.owl
         description: A persistent OBO CURIE pointing to the latest version of the Mondo ontology.
@@ -399,13 +414,19 @@ slots:
   object_source_version:
     description: Version IRI or version string of the source of the object term.
     range: string
+    instantiates: sssom:Propagatable
+    annotations:
+      propagated: true
     examples:
       - value: http://purl.obolibrary.org/obo/mondo/releases/2021-01-30/mondo.owl
         description: (A persistent Version IRI pointing to the Mondo version '2021-01-30')
   mapping_provider:
     description: URL pointing to the source that provided the mapping, for example
       an ontology that already contains the mappings, or a database from which it was derived.
     range: uri
+    instantiates: sssom:Propagatable
+    annotations:
+      propagated: true
   mapping_set_source:
     description: A mapping set or set of mapping set that was used to derive the mapping set.
     slot_uri: prov:wasDerivedFrom
@@ -430,17 +451,26 @@ slots:
     description: A reference to the tool or algorithm that was used to generate the
       mapping. Should be a URL pointing to more info about it, but can be free text.
     range: string
+    instantiates: sssom:Propagatable
+    annotations:
+      propagated: true
     examples:
       - value: https://github.com/AgreementMakerLight/AML-Project
   mapping_tool_version:
     description: Version string that denotes the version of the mapping tool used.
     range: string
+    instantiates: sssom:Propagatable
+    annotations:
+      propagated: true
     examples:
       - value: v3.2
   mapping_date:
     description: The date the mapping was asserted. This is different from the date the mapping was published or compiled in a SSSOM file.
     slot_uri: pav:authoredOn
     range: date
+    instantiates: sssom:Propagatable
+    annotations:
+      propagated: true
   publication_date:
     description: The date the mapping was published. This is different from the date the mapping was asserted.
     slot_uri: dcterms:created
@@ -454,11 +484,17 @@ slots:
       for the match.
     range: EntityReference
     multivalued: true
+    instantiates: sssom:Propagatable
+    annotations:
+      propagated: true
   object_match_field:
     description: A list of properties (term annotations on the object) that was used
       for the match.
     range: EntityReference
     multivalued: true
+    instantiates: sssom:Propagatable
+    annotations:
+      propagated: true
   match_string:
     description: String that is shared by subj/obj. It is recommended to indicate the 
       fields for the match using the object and subject_match_field slots.
@@ -470,6 +506,9 @@ slots:
       recommended to store the match in separate rows.
     range: EntityReference
     multivalued: true
+    instantiates: sssom:Propagatable
+    annotations:
+      propagated: true
     examples:
       - value: semapv:Stemming
       - value: semapv:StopWordRemoval
@@ -479,6 +518,9 @@ slots:
       recommended to store the match in separate rows.
     range: EntityReference
     multivalued: true
+    instantiates: sssom:Propagatable
+    annotations:
+      propagated: true
     examples:
       - value: semapv:Stemming
       - value: semapv:StopWordRemoval
@@ -722,3 +764,14 @@ classes:
       - mapping_set_group
       - last_updated
       - local_name
+  Propagatable:
+    class_uri: sssom:Propagatable
+    description: Metamodel extension class to describe slots whose value can be
+      propagated down from the MappingSet class to the Mapping class.
+    see_also:
+      - https://github.com/mapping-commons/sssom/issues/305
+    attributes:
+      propagated:
+        description: Indicates whether a slot can be propagated from a mapping
+          down to individual mappings.
+        range: boolean