Add new "literal profile" solution based on "subject_label" and "obje…

…ct_label" (#384)

Resolves #234

This PR introduces an alternative model to the "literal mapping"
proposal we have previously added. It is built on the following
principles:

- Introducing a profile causes a needless overhead which requires
specialised tooling
- We can achieve the same functionality with a _very_ minimal
intervention in the main metadata model

I do understand that there are various opposing views on the need for a "literal" profile, but I think this super minimal intervention will satisfy both sides. In essence, we do not have a literal profile; we have a convention that allows us to represent an "entity" by its label (subject_label) rather than by a semantic identifier. This means we do not need specialised tooling and documentation (nor training).

Huge thanks to @gouttegd 🙏 who managed to steer this massive carrier ship after it had left the harbor. This is rarely successful and needed a huge amount of thought, testing, and patience (mostly with me and my constant questions), and I am supremely happy we managed to make it!

---------

Co-authored-by: Damien Goutte-Gattat <[email protected]>
Co-authored-by: Damien Goutte-Gattat <[email protected]>

CHANGELOG.md

@@ -5,6 +5,7 @@
 - Add the concept of "propagatable slots".
 - Add the `curie_map` to the model (instead of it being a specificity of the SSSOM/TSV format).
 - Add the concept of "extension slots".
+- Add the concept of "literal mappings".
 - Add the entity reference `sssom:NoTermFound` to express the concept of an "unmapped entity" ([issue](https://github.com/mapping-commons/sssom/issues/28))
 - Replace `semantic_similarity_score` with `similarity_score` and `semantic_similarity_measure` with `similarity_measure` in the data model ([issue](https://github.com/mapping-commons/sssom/issues/385))
 

examples/schema/literals.sssom.tsv

@@ -0,0 +1,9 @@
+#curie_map:
+#  COMENT: https://example.com/entities/
+#mapping_set_id: https://example.org/sets/literal-mappings
+#license: https://creativecommons.org/licenses/by/4.0/
+subject_label	predicate_id	object_id	object_label	mapping_justification	subject_type
+alice	skos:closeMatch	COMENT:0011	alpha	semapv:ManualMappingCuration	rdfs literal
+bob	skos:closeMatch	COMENT:0012	beta	semapv:ManualMappingCuration	rdfs literal
+daphne	skos:closeMatch	COMENT:0014	delta	semapv:ManualMappingCuration	rdfs literal
+eve	skos:closeMatch	COMENT:0015	epsilon	semapv:ManualMappingCuration	rdfs literal

mkdocs.yml

@@ -33,7 +33,6 @@ nav:
       - Introduction: spec-model.md
       - Applying Chaining Rules: chaining-rules.md
       - LinkML documentation: linkml-index.md
-      - SSSOM profiles: sssom-profiles.md
     - Serialisations:
       - Introduction: spec-formats.md
       - SSSOM/TSV serialisation: spec-formats-tsv.md

src/docs/spec-model.md

@@ -92,6 +92,25 @@ In addition, predicates from the following sources MAY also be encouraged:
 * any relation under [skos:mappingRelation](http://www.w3.org/2004/02/skos/core#mappingRelation) in the [Semantic Mapping Vocabulary](https://mapping-commons.github.io/semantic-mapping-vocabulary/).
 
 
+## Literal mappings
+
+<a id="literal-mappings"></a>
+
+The SSSOM model is primarily intended to represent mappings between semantic entities. However, it may also be used to represent mappings where at least one side is a literal string that does not have an identifier of its own. Any such mapping is henceforth called a _literal mapping_.
+
+To represent a mapping whose subject (resp. object) is a literal:
+
+* the `subject_type` (resp. `object_type`) slot MUST be set to `rdfs literal`;
+* the `subject_label` (resp. `object_label`) slot MUST be set to the literal itself;
+* the `subject_id` (resp. `object_id`) slot MAY be left empty.
+
+The last point is an exception to the normal rules about required slots, which state that a mapping must always have a `subject_id` and an `object_id`. Implementations MUST accept a mapping without a `subject_id` (resp. `object_id`) _if and only if_ the `subject_type` (resp. `object_type`) slot is set to `rdfs literal`.
+
+All other slots in the `Mapping` class may be used normally in a literal mapping, with the same meaning as for a non-literal mapping.
+
+When computing the cardinality of mappings in a set (e.g. to set the value of the `mapping_cardinality` slot), if the mapping has a literal subject (resp. object), then the `subject_label` (resp. `object_label`) slot must be used for determining the number of occurrences of the subject (resp. object) in the set.
+
+
 ## Representing unmapped entities
 
 The special value `sssom:NoTermFound` MAY be used as the `object_id` of a mapping to explicitly state that the subject of said mapping cannot be mapped to any entity in the domain represented by the `object_source` slot.

src/sssom_schema/schema/sssom_schema.yaml

@@ -45,10 +45,16 @@ enums:
         meaning: rdfs:Class
       rdfs literal:
         meaning: rdfs:Literal
+        description: This value indicate that the entity being mapped is not a semantic entity with a distinct identifier, but is instead represented entirely by its literal label. This value MUST NOT be used in the predicate_type slot.
+        see_also:
+        - https://mapping-commons.github.io/sssom/spec-model/#literal-mappings
+        - https://github.com/mapping-commons/sssom/issues/234
+        - https://github.com/mapping-commons/sssom/blob/master/examples/schema/literals.sssom.tsv
       rdfs datatype:
         meaning: rdfs:Datatype
       rdf property:
         meaning: rdf:Property
+
   predicate_modifier_enum:
     permissible_values:
       Not: Negating the mapping predicate. The meaning of the triple becomes subject_id is not a predicate_id match to object_id.
@@ -132,7 +138,6 @@ slots:
   subject_id:
     description: The ID of the subject of the mapping.
     range: EntityReference
-    required: true
     mappings:
     - owl:annotatedSource
     slot_uri: owl:annotatedSource
@@ -231,7 +236,6 @@ slots:
     mappings:
     - owl:annotatedTarget
     range: EntityReference
-    required: true
     slot_uri: owl:annotatedTarget
     examples:
       - value: HP:0009894
@@ -689,6 +693,41 @@ classes:
     - other
     - comment
     class_uri: owl:Axiom
+    rules:
+      - preconditions:
+          slot_conditions:
+            subject_type: 
+              equals_string: "rdfs literal"
+        postconditions:
+          slot_conditions:
+            subject_label:
+              required: true
+      - preconditions:
+          slot_conditions:
+            subject_type:
+              none_of:
+                equals_string: "rdfs literal"
+        postconditions:
+          slot_conditions:
+            subject_id:
+              required: true
+      - preconditions:
+          slot_conditions:
+            object_type: 
+              equals_string: "rdfs literal"
+        postconditions:
+          slot_conditions:
+            object_label:
+              required: true
+      - preconditions:
+          slot_conditions:
+            object_type:
+              none_of:
+                equals_string: "rdfs literal"
+        postconditions:
+          slot_conditions:
+            object_id:
+              required: true
   mapping registry:
     description: A registry for managing mapping sets. It holds a set of 
       mapping set references, and can import other registries.