From ae59c3ec1d14af48fc999163e9a19f6332696ca5 Mon Sep 17 00:00:00 2001 From: Damien Goutte-Gattat Date: Mon, 11 Aug 2025 20:18:21 +0100 Subject: [PATCH 1/5] Add 0:0 special cardinality value. This commit adds a new cardinality value of `0:0`, to be used for mapping records where both the `subject_id` and the `object_id` are sssom:NoTermFound. Such records are allowed and may be used to represent the fact that there is no overlap between a subject vocabulary and an object vocabulary. We also try to explain a bit more what the different cardinality values mean exactly, and provide two examples: * one that illustrates all possible cardinality values between real mappings (1:1, 1:n, n:1, n:n); * one that illustrates the special cases where the subject_id and/or the object_id is sssom:NoTermFound. closes #477 --- CHANGELOG.md | 1 + ...rdinality-with-unmapped-entities.sssom.tsv | 11 ++++ examples/schema/cardinality.sssom.tsv | 15 ++++++ src/docs/spec-model.md | 3 +- src/sssom_schema/schema/sssom_schema.yaml | 52 ++++++++++++++----- 5 files changed, 69 insertions(+), 13 deletions(-) create mode 100644 examples/schema/cardinality-with-unmapped-entities.sssom.tsv create mode 100644 examples/schema/cardinality.sssom.tsv diff --git a/CHANGELOG.md b/CHANGELOG.md index c1bf14a5..182c558b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,7 @@ - Add `record_id` slot to the `Mapping` class ([issue](https://github.com/mapping-commons/sssom/issues/359)). - Change all URI-typed slots to clarify that they expect _non-relative_ URIs as values ([issue](https://github.com/mapping-commons/sssom/issues/448)). - Add `cardinality_scope` slot ([issue](https://github.com/mapping-commons/sssom/issues/467)). +- Add new value `0:0` to the `mapping_cardinality_enum` ([issue](https://github.com/mapping-commons/sssom/issues/477)). ## SSSOM version 1.0.0 diff --git a/examples/schema/cardinality-with-unmapped-entities.sssom.tsv b/examples/schema/cardinality-with-unmapped-entities.sssom.tsv new file mode 100644 index 00000000..64327991 --- /dev/null +++ b/examples/schema/cardinality-with-unmapped-entities.sssom.tsv @@ -0,0 +1,11 @@ +#curie_map: +# OBJ: https://example.org/object/ +# SRC: https://example.org/sources/ +# SUBJ: https://example.org/subject/ +#mapping_set_id: https://example.org/sets/cardinality-with-unmapped-entities +#license: https://creativecommons.org/licenses/by/4.0/ +subject_id predicate_id object_id mapping_justification subject_source object_source mapping_cardinality comment +SUBJ:0001 skos:exactMatch sssom:NoTermFound semapv:ManualMappingCuration SRC:A SRC:B 1:0 S1 in vocabulary A has no exact match in vocabulary B +SUBJ:0001 skos:closeMatch OBJ:0001 semapv:ManualMappingCuration SRC:A SRC:B 1:1 S1 mapped only to O1, O1 mapped only to S1 -- the record involving sssom:NoTermFound does not count, as it an absence of match rather than an actual mapping +sssom:NoTermFound skos:exactMatch OBJ:0002 semapv:ManualMappingCuration SRC:C SRC:D 0:1 O1 in vocabulary D has no exact match in vocabulary C +sssom:NoTermFound skos:exactMatch sssom:NoTermFound semapv:ManualMappingCuration SRC:E SRC:F 0:0 No exact match between any term ffrom vocabulary E and any term for vocabulary F (in other words, the two vocabularies are completely disjoint, at least as far as exact matches are considered) diff --git a/examples/schema/cardinality.sssom.tsv b/examples/schema/cardinality.sssom.tsv new file mode 100644 index 00000000..dd68fd73 --- /dev/null +++ b/examples/schema/cardinality.sssom.tsv @@ -0,0 +1,15 @@ +#curie_map: +# OBJ: https://example.org/object/ +# SUBJ: https://example.org/subject/ +#mapping_set_id: https://example.org/sets/cardinality +#license: https://creativecommons.org/licenses/by/4.0/ +subject_id predicate_id object_id mapping_justification mapping_cardinality comment +SUBJ:0001 skos:exactMatch OBJ:0001 semapv:LexicalMatching 1:1 S1 and O2 only mapped to each other +SUBJ:0001 skos:exactMatch OBJ:0001 semapv:MappingReview 1:1 S1 and O2 only mapped to each other +SUBJ:0002 skos:exactMatch OBJ:0002 semapv:LexicalMatching 1:n S2 mapped to both O2 and O3, O2 mapped only to S2 +SUBJ:0002 skos:exactMatch OBJ:0003 semapv:LexicalMatching 1:n S2 mapped to both O2 and O3, O3 mapped only to S2 +SUBJ:0003 skos:exactMatch OBJ:0004 semapv:LexicalMatching n:1 S3 and S4 both mapped to only O4 +SUBJ:0004 skos:exactMatch OBJ:0004 semapv:LexicalMatching n:1 S3 and S4 both mapped to only O4 +SUBJ:0005 skos:exactMatch OBJ:0005 semapv:LexicalMatching n:n S5 mapped to O5 and O6, O5 mapped to S5 and S6 +SUBJ:0005 skos:exactMatch OBJ:0006 semapv:LexicalMatching 1:n S5 mapped to O5 and O6, O6 mapped only to S5 +SUBJ:0006 skos:exactMatch OBJ:0005 semapv:LexicalMatching n:1 S6 mapped only to O5, O5 mapped to both S5 and S6 diff --git a/src/docs/spec-model.md b/src/docs/spec-model.md index cec4eb13..3173db98 100644 --- a/src/docs/spec-model.md +++ b/src/docs/spec-model.md @@ -126,7 +126,7 @@ The `sssom:NoTermFound` value MUST NOT be used in any other slot than `subject_i The meaning of the NOT predicate modifier in a mapping that refers to `sssom:NoTermFound` is unspecified. -When computing cardinality values (to fill the `mapping_cardinality` slot), mappings that refer to `sssom:NoTermFound` MUST be ignored. +When computing cardinality values (to fill the `mapping_cardinality` slot): (1) a mapping record with a `object_id` (respectively `subject_id` of `sssom:NoTermFound` MUST be assigned a cardinality value of `1:0` (respectively `0:1`), regardless of any other record; (2) a mapping record with both the `subject_id` and the `object_id` set to `sssom:NoTermFound` MUST be assigned a cardinality value of `0:0`, regardless of any other record; (3) such records MUST be ignored when computing the cardinality of other records. ## Mapping cardinality and cardinality scope @@ -285,3 +285,4 @@ Not all changes can be annotated thusly in the LinkML model, though. For changes * The value `composed entity expression` has been added to the `EntityType` enumeration. * The type of the `see_also` slot has been changed to `sssom:NonRelativeURI`. When parsing a SSSOM 1.0 set, implementations SHOULD accept arbitrary string values in that slot. * All slots that were typed as `xsd:anyURI` have been re-typed as `sssom:NonRelativeURI`. When parsing a SSSOM 1.0 set, implementations SHOULD accept relative URI values in those slots. +* A new value `0:0` has been added to the `mapping_cardinality_enum`. diff --git a/src/sssom_schema/schema/sssom_schema.yaml b/src/sssom_schema/schema/sssom_schema.yaml index 72601bd5..4e47a63b 100644 --- a/src/sssom_schema/schema/sssom_schema.yaml +++ b/src/sssom_schema/schema/sssom_schema.yaml @@ -76,12 +76,30 @@ enums: meaning: sssom:NegatedPredicate mapping_cardinality_enum: permissible_values: - "1:1": One-to-one mapping - "1:n": One-to-many mapping - "n:1": Many-to-one mapping - "1:0": One-to-none mapping - "0:1": None-to-one mapping - "n:n": Many-to-many mapping + "1:1": + description: Indicates the mapping record is about a one-to-one mapping, that is, + the subject and the object are only mapped to each other, exclusive of any + other subject or object. + "1:n": + description: Indicates the mapping record is about a one-to-many mapping, that + is, the same subject is mapped to several different objects. + "n:1": + description: Indicates the mapping record is about a many-to-one mapping, that + is, several different subjects are mapped to the same object. + "n:n": + description: Indicates the mapping record is about a many-to-many mapping, that + is, the subject is maapped to several different objects and the object is + mapped to several different subjects. + "1:0": + description: Indicates that the subject has no match in the object vocabulary. + This value MUST only be used when the object_id is sssom:NoTermFound. + "0:1": + description: Indicates that the object has no match in the subject vocabulary. + This value MUST only be used when the subject_id is sssom:NoTermFound. + "0:0": + description: Indicates that there is no match between the subject vocabulary + and the object vocabulary. This value MUST only be used when both the + subject_id and the object_id are sssom:NoTermFound. types: EntityReference: @@ -574,17 +592,27 @@ slots: - value: MONDO_MAPPINGS:mondo_exactmatch_ncit.sssom.tsv description: A reference to the mapping set that originally contained this mapping. mapping_cardinality: - description: A string indicating whether this mapping is from a 1:1 (the subject_id - maps to a single object_id), 1:n (the subject maps to more than one object_id), - n:1, 1:0, 0:1 or n:n group. Note that this is a convenience field that should be derivable - from the mapping set. + description: A value indicating whether the subject (respectively object) of this + mapping record is present in other records involving a different object + (respectively subject), within the subset of records defined by the + cardinality_scope slot (or within the entire mapping set if cardinality_scope + is undefined). + Note that this is a convenience field, whose values can always be derived from + the mapping set. range: mapping_cardinality_enum examples: - value: "1:1" - description: A one-to-one mapping. + description: A one-to-one mapping. There are no other records in which the same + subject is mapped to a different object, and no other records in which the + same object is mapped to a different subject. - value: "1:n" - description: A one-to-many mapping. + description: A one-to-many mapping. There are other records in which the same + subject is mapped to at least one different object than the object present in + this record; there are no other records in which the object is mapped to a + different subject. see_also: + - https://github.com/mapping-commons/sssom/blob/master/examples/schema/cardinality.sssom.tsv + - https://github.com/mapping-commons/sssom/blob/master/examples/schema/cardinality-with-unmapped-entities.sssom.tsv - https://github.com/mapping-commons/sssom/blob/master/examples/schema/cardinality-scope-empty.sssom.tsv cardinality_scope: description: A list of mapping slots that define the scope for the value found From ffbd252d4a3d367ab8d00c6eb1afe40a83c5086a Mon Sep 17 00:00:00 2001 From: Damien Goutte-Gattat Date: Mon, 11 Aug 2025 20:39:05 +0100 Subject: [PATCH 2/5] Fix typo and missing parenthesis. --- src/docs/spec-model.md | 2 +- src/sssom_schema/schema/sssom_schema.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/docs/spec-model.md b/src/docs/spec-model.md index 3173db98..769099d0 100644 --- a/src/docs/spec-model.md +++ b/src/docs/spec-model.md @@ -126,7 +126,7 @@ The `sssom:NoTermFound` value MUST NOT be used in any other slot than `subject_i The meaning of the NOT predicate modifier in a mapping that refers to `sssom:NoTermFound` is unspecified. -When computing cardinality values (to fill the `mapping_cardinality` slot): (1) a mapping record with a `object_id` (respectively `subject_id` of `sssom:NoTermFound` MUST be assigned a cardinality value of `1:0` (respectively `0:1`), regardless of any other record; (2) a mapping record with both the `subject_id` and the `object_id` set to `sssom:NoTermFound` MUST be assigned a cardinality value of `0:0`, regardless of any other record; (3) such records MUST be ignored when computing the cardinality of other records. +When computing cardinality values (to fill the `mapping_cardinality` slot): (1) a mapping record with a `object_id` (respectively `subject_id`) of `sssom:NoTermFound` MUST be assigned a cardinality value of `1:0` (respectively `0:1`), regardless of any other record; (2) a mapping record with both the `subject_id` and the `object_id` set to `sssom:NoTermFound` MUST be assigned a cardinality value of `0:0`, regardless of any other record; (3) such records MUST be ignored when computing the cardinality of other records. ## Mapping cardinality and cardinality scope diff --git a/src/sssom_schema/schema/sssom_schema.yaml b/src/sssom_schema/schema/sssom_schema.yaml index 4e47a63b..db9c00d9 100644 --- a/src/sssom_schema/schema/sssom_schema.yaml +++ b/src/sssom_schema/schema/sssom_schema.yaml @@ -88,7 +88,7 @@ enums: is, several different subjects are mapped to the same object. "n:n": description: Indicates the mapping record is about a many-to-many mapping, that - is, the subject is maapped to several different objects and the object is + is, the subject is mapped to several different objects and the object is mapped to several different subjects. "1:0": description: Indicates that the subject has no match in the object vocabulary. From 909d2afe794139e0ce5532682941d2ca6991ffbb Mon Sep 17 00:00:00 2001 From: Damien Goutte-Gattat Date: Tue, 12 Aug 2025 06:37:55 +0100 Subject: [PATCH 3/5] Fix comments in cardinality examples. --- examples/schema/cardinality-with-unmapped-entities.sssom.tsv | 4 ++-- examples/schema/cardinality.sssom.tsv | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/examples/schema/cardinality-with-unmapped-entities.sssom.tsv b/examples/schema/cardinality-with-unmapped-entities.sssom.tsv index 64327991..945a2950 100644 --- a/examples/schema/cardinality-with-unmapped-entities.sssom.tsv +++ b/examples/schema/cardinality-with-unmapped-entities.sssom.tsv @@ -6,6 +6,6 @@ #license: https://creativecommons.org/licenses/by/4.0/ subject_id predicate_id object_id mapping_justification subject_source object_source mapping_cardinality comment SUBJ:0001 skos:exactMatch sssom:NoTermFound semapv:ManualMappingCuration SRC:A SRC:B 1:0 S1 in vocabulary A has no exact match in vocabulary B -SUBJ:0001 skos:closeMatch OBJ:0001 semapv:ManualMappingCuration SRC:A SRC:B 1:1 S1 mapped only to O1, O1 mapped only to S1 -- the record involving sssom:NoTermFound does not count, as it an absence of match rather than an actual mapping -sssom:NoTermFound skos:exactMatch OBJ:0002 semapv:ManualMappingCuration SRC:C SRC:D 0:1 O1 in vocabulary D has no exact match in vocabulary C +SUBJ:0001 skos:closeMatch OBJ:0001 semapv:ManualMappingCuration SRC:A SRC:B 1:1 S1 mapped only to O1, O1 mapped only to S1 -- the record involving sssom:NoTermFound does not count, as it is an absence of match rather than an actual mapping +sssom:NoTermFound skos:exactMatch OBJ:0002 semapv:ManualMappingCuration SRC:C SRC:D 0:1 O2 in vocabulary D has no exact match in vocabulary C sssom:NoTermFound skos:exactMatch sssom:NoTermFound semapv:ManualMappingCuration SRC:E SRC:F 0:0 No exact match between any term ffrom vocabulary E and any term for vocabulary F (in other words, the two vocabularies are completely disjoint, at least as far as exact matches are considered) diff --git a/examples/schema/cardinality.sssom.tsv b/examples/schema/cardinality.sssom.tsv index dd68fd73..24f57a33 100644 --- a/examples/schema/cardinality.sssom.tsv +++ b/examples/schema/cardinality.sssom.tsv @@ -4,8 +4,8 @@ #mapping_set_id: https://example.org/sets/cardinality #license: https://creativecommons.org/licenses/by/4.0/ subject_id predicate_id object_id mapping_justification mapping_cardinality comment -SUBJ:0001 skos:exactMatch OBJ:0001 semapv:LexicalMatching 1:1 S1 and O2 only mapped to each other -SUBJ:0001 skos:exactMatch OBJ:0001 semapv:MappingReview 1:1 S1 and O2 only mapped to each other +SUBJ:0001 skos:exactMatch OBJ:0001 semapv:LexicalMatching 1:1 S1 and O1 only mapped to each other +SUBJ:0001 skos:exactMatch OBJ:0001 semapv:MappingReview 1:1 S1 and O1 only mapped to each other SUBJ:0002 skos:exactMatch OBJ:0002 semapv:LexicalMatching 1:n S2 mapped to both O2 and O3, O2 mapped only to S2 SUBJ:0002 skos:exactMatch OBJ:0003 semapv:LexicalMatching 1:n S2 mapped to both O2 and O3, O3 mapped only to S2 SUBJ:0003 skos:exactMatch OBJ:0004 semapv:LexicalMatching n:1 S3 and S4 both mapped to only O4 From 88f87eefbf24e644b15cfa3f6dfd855383f916fc Mon Sep 17 00:00:00 2001 From: Damien Goutte-Gattat Date: Tue, 12 Aug 2025 14:07:03 +0100 Subject: [PATCH 4/5] Fix typo. Co-authored-by: Nico Matentzoglu --- examples/schema/cardinality-with-unmapped-entities.sssom.tsv | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/schema/cardinality-with-unmapped-entities.sssom.tsv b/examples/schema/cardinality-with-unmapped-entities.sssom.tsv index 945a2950..f4e24d13 100644 --- a/examples/schema/cardinality-with-unmapped-entities.sssom.tsv +++ b/examples/schema/cardinality-with-unmapped-entities.sssom.tsv @@ -8,4 +8,4 @@ subject_id predicate_id object_id mapping_justification subject_source object_so SUBJ:0001 skos:exactMatch sssom:NoTermFound semapv:ManualMappingCuration SRC:A SRC:B 1:0 S1 in vocabulary A has no exact match in vocabulary B SUBJ:0001 skos:closeMatch OBJ:0001 semapv:ManualMappingCuration SRC:A SRC:B 1:1 S1 mapped only to O1, O1 mapped only to S1 -- the record involving sssom:NoTermFound does not count, as it is an absence of match rather than an actual mapping sssom:NoTermFound skos:exactMatch OBJ:0002 semapv:ManualMappingCuration SRC:C SRC:D 0:1 O2 in vocabulary D has no exact match in vocabulary C -sssom:NoTermFound skos:exactMatch sssom:NoTermFound semapv:ManualMappingCuration SRC:E SRC:F 0:0 No exact match between any term ffrom vocabulary E and any term for vocabulary F (in other words, the two vocabularies are completely disjoint, at least as far as exact matches are considered) +sssom:NoTermFound skos:exactMatch sssom:NoTermFound semapv:ManualMappingCuration SRC:E SRC:F 0:0 No exact match between any term from vocabulary E and any term for vocabulary F (in other words, the two vocabularies are completely disjoint, at least as far as exact matches are considered) From 18b94b1108a6b4c1d7566ba474795cb021e1516d Mon Sep 17 00:00:00 2001 From: Damien Goutte-Gattat Date: Sun, 17 Aug 2025 10:24:01 +0100 Subject: [PATCH 5/5] Typo fix. Co-authored-by: Emily Hartley --- src/sssom_schema/schema/sssom_schema.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/sssom_schema/schema/sssom_schema.yaml b/src/sssom_schema/schema/sssom_schema.yaml index 6c93b8db..ed9fa2b5 100644 --- a/src/sssom_schema/schema/sssom_schema.yaml +++ b/src/sssom_schema/schema/sssom_schema.yaml @@ -95,7 +95,7 @@ enums: This value MUST only be used when the object_id is sssom:NoTermFound. "0:1": description: Indicates that the object has no match in the subject vocabulary. - This value MUST only be used when the subject_id is sssom:NoTermFound. + This value MUST only be used when the subject_id is sssom:NoTermFound. "0:0": description: Indicates that there is no match between the subject vocabulary and the object vocabulary. This value MUST only be used when both the