SSSOM Mapping Set
One of the key deliverables of the Health-RI Semantic Interoperability Initiative is a SSSOM mapping set. This mapping set is manually curated, reflecting the efforts of both the dedicated mapping team and external collaborators. For the conceptual background and rationale behind our mappings, see the Mapping Strategy.
This page documents the mappings curated and published by Health-RI. Partners may also embed mappings directly into their own ontologies, as explained in the Mapping Strategy.
Permanent URIs
We offer several stable and accessible URIs for accessing the mapping set in different formats:
https://github.com/Health-RI/semantic-interoperability/mappings— Redirects to the TTL version of the SSSOM mappings.https://github.com/Health-RI/semantic-interoperability/mappings/ttl— Redirects to the TTL version of the SSSOM mappings.https://github.com/Health-RI/semantic-interoperability/mappings/tsv— Redirects to the TSV version of the SSSOM mappings.
Versioning Strategy
Unlike the Health-RI Ontology (which may use semantic versioning or other schemes), the mapping set versioning is based on the YYYY-MM-DD format, corresponding to its publication date. There will be at most one version released per day.
Importantly, mappings cannot be removed once they’re published. To revise a mapping (e.g., if it was erroneous or needs replacement), we use the replaces field to refer back to the original entry that the new one supersedes.
SSSOM File Schema
Below is the schema for the SSSOM TSV file, with each field’s link to the specification, expected datatype, cardinality, mandatory status, a concise description, and an illustrative example:
| Field | Type | Cardinality | Mandatory | Description | Example | Provided by |
|---|---|---|---|---|---|---|
| record_id | EntityReference | 1 | Yes | Unique ID of the mapping record | http://health-ri.org/mappings/rec123 |
Curator |
| subject_id | EntityReference | 1 | Yes | Identifier of the subject entity | fhir:Patient |
Contributor |
| subject_label | String | 0..1 | No | Label of the subject entity | Patient |
Contributor |
| predicate_id | EntityReference | 1 | Yes | Relation linking subject and object | hriv:hasSemantics |
Contributor |
| predicate_modifier | PredicateModifierEnum | 0..1 | No | A modifier for negating the predicate1 | Not |
Contributor (Optional) |
| object_id | EntityReference | 1 | Yes | Identifier of the object entity | hrio:Person |
Contributor |
| object_label | String | 0..1 | No | Label of the object entity | Person |
Contributor |
| object_category | String | 0..1 | No | OntoUML stereotype of the object | Kind |
Contributor |
| mapping_justification | EntityReference | 1 | Yes | Method or rationale for creating a mapping2 | semapv:ManualMappingCuration |
Contributor (or Default) |
| author_id | EntityReference(s) | 1..* | Yes | Identifier(s) of who created the mapping | orcid:0000-0003-2736-7817 |
Contributor |
| author_label | String(s) | 0..* | No | Name(s) of the mapping author(s) | Pedro P. F. Barcelos |
Contributor |
| reviewer_id | EntityReference(s) | 0..* | No | Identifier(s) of mapping reviewer(s) | orcid:0000-0001-2345-6789 |
Contributor |
| reviewer_label | String(s) | 0..* | No | Name(s) of the mapping reviewer(s) | Jane Doe |
Contributor |
| creator_id | EntityReference | 1 | Yes | Agent responsible for publishing the mapping | https://w3id.org/health-ri/semantic-interoperability |
System (Fixed) |
| creator_label | String | 1 | Yes | Name of the publishing agent | Health-RI Semantic Interoperability |
System (Fixed) |
| license | NonRelativeURI | 1 | Yes | License governing mapping use | https://creativecommons.org/licenses/by/4.0/ |
Contributor (or Default) |
| subject_type | EntityTypeEnum | 0..1 | No | Type of the subject entity | owl:Class |
Contributor |
| subject_source | EntityReference | 0..1 | No | Source vocabulary of the subject entity | fhir:http://hl7.org/fhir |
Contributor |
| subject_source_version | String | 0..1 | No | Version of the subject source | R4 |
Contributor |
| object_source | EntityReference | 1 | Yes | Source vocabulary of the object3 | hrio:http://w3id.org/health-ri/ontology/v0.9.1 |
Contributor (or Default) |
| mapping_date | Date | 1 | Yes | Date when mapping was created (format: YYYY-MM-DD) | 2025-07-02 |
Contributor |
| publication_date | Date | 1 | Yes | Date when mapping was published (format: YYYY-MM-DD) | 2025-07-30 |
System (Generated) |
| replaces | EntityReference(s) | 0..* | No | Indicates that this mapping record replaces another | http://health-ri.org/mappings/rec122 |
Contributor |
| isReplacedBy | EntityReference(s) | 0..* | No | Indicates that this mapping record is replaced by another4 | http://health-ri.org/mappings/rec124 |
System (Generated) |
| comment | String | 0..1 | No | Free-text notes about the mapping | Reviewed for consistency with ontology v0.9.1. |
Contributor |
Responsibility Legend
The following legend explains who is responsible for providing or assigning each field in the schema, clarifying whether values come from contributors, curators, or are system-generated:
- Contributor – Must be provided in PRs.
- Curator – Added manually by Health-RI curators.
- Contributor (or Default) – Contributor should provide this; if omitted, the system assigns a default.
- System (Fixed) – Always set to a fixed value, cannot be changed.
- System (Generated) – Automatically assigned at publication time, not editable.
Type Legend
The following table lists and defines all datatypes used in the schema above, according to the SSSOM specification:
| Type | Definition | Example |
|---|---|---|
| EntityReference | A CURIE or URI referring to an entity in a vocabulary or ontology. | fhir:Patient |
| EntityReference(s) | One or more CURIEs or URIs referring to entities in vocabularies or ontologies. | orcid:0000-0003-2736-7817 \| orcid:0000-0001-2345-6789 |
| String | A literal string value, typically plain text. | Patient |
| String(s) | One or more literal string values, typically plain text. | Pedro P. F. Barcelos \| Jane Doe |
| NonRelativeURI | An absolute URI (non-relative), typically identifying a web resource. | https://creativecommons.org/licenses/by/4.0/ |
| EntityTypeEnum | A controlled vocabulary of entity types (e.g., owl:Class, rdf:Property). |
owl:Class |
| Date | A calendar date in ISO 8601 format (YYYY-MM-DD). | 2025-07-02 |
Default Values
Some fields in the schema have predefined default values automatically assigned when contributors do not provide them:
- mapping_justification – Defaults to
semapv:ManualMappingCuration - license – Defaults to
https://creativecommons.org/licenses/by/4.0/ - object_source – Defaults to
http://w3id.org/health-ri/ontology
How to Contribute
We welcome contributions to expand and refine the mapping set. You can contribute in two ways:
-
Preferred: Submit the Issue Form
Use our SSSOM mapping issue form to add a single mapping row. Fill in the required fields and submit; Health-RI curators will review and integrate your contribution. -
Alternative: Use the Excel template
Download the XLSX template and enter:
- the mapping row(s) in the mappings sheet, and
- all CURIE prefix bindings in the prefix sheet.
Attach the completed file to a new issue and we’ll review and add it. In the template, all mandatory fields's headers are in black background, while the optional ones are in green.
Both methods ensure your contribution is reviewed and incorporated into the official Health-RI SSSOM mapping set.
Submission checklist (for contributors)
Before submitting, please verify the following to ensure your contribution is complete and compliant with the schema:
- All mandatory contributor fields are present and correctly formatted.
- Any optional values provided use valid identifiers (e.g., ORCIDs, resolvable URIs, SEMAPV terms).
- If pinning a version,
object_sourceis a specific version URI (not a generic one).
-
May either be set to
Not(its only valid value) or left empty. It is used specifically to express a negated mapping predicate. ↩ -
Currently, the only acceptable value for
mapping_justificationissemapv:ManualMappingCuration, or a comparable alternative subject to curator evaluation. This constraint is essential for maintaining the necessary semantic alignment. ↩ -
When using the default, it always resolves to the Health-RI ontology (latest version). If contributors provide a value, it must be either a specific version URI or the latest version URI. ↩
-
It is automatically calculated and asserted at publication time. When a new mapping entry uses the
replacesfield to supersede an older one, the system assigns the correspondingisReplacedByvalue to the replaced entry, ensuring both directions of the relation are represented. ↩