The Health-RI SSSOM Mapping Set Schema
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.
Want to browse the mappings?
For an interactive view of the already created mappings, see Mappings.
Permanent URIs
We offer several stable and accessible URIs for accessing the mapping set in different formats:
https://w3id.org/health-ri/semantic-interoperability/mappings— Redirects to the TTL version of the SSSOM mappings.https://w3id.org/health-ri/semantic-interoperability/mappings/ttl— Redirects to the TTL version of the SSSOM mappings.https://w3id.org/health-ri/semantic-interoperability/mappings/tsv— Redirects to the TSV version of the SSSOM mappings.
What are Permanent (Persistent) URIs?
See W3C Cool URIs don't change for the design principles behind stable, resolvable identifiers, and the w3id community service for implementing them in practice.
Versioning Strategy
As per the authoritative policy in the Mapping Governance page's Versioning and Change Control section, releases are dated YYYY-MM-DD (at most one per calendar day) and records are append-only via replaces.
For lifecycle states, approvals, and publication policy, see the Governance, Lifecycle, and Validation of the Health-RI SSSOM Mapping Set page.
Why append-only?
An append-only approach (immutable log) preserves a complete audit trail, makes releases reproducible, and avoids ambiguity about which version of a mapping was used.
SSSOM File Schema
Language tags for labels
The subject_label and object_label fields must be language-tagged (RDF langstrings), e.g., Patient@en, Patiënt@nl.
What is a language-tagged string?
In RDF, a language-tagged string is a literal paired with a BCP 47 language tag (e.g., Patient@en, Patiënt@nl). See: W3C RDF Schema 1.1 (rdf:langString) and RFC 5646 (BCP 47 tags).
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 | hrim:1c56bebe1 |
Curator |
| subject_id | EntityReference | 1 | Yes | Identifier of the subject entity | fhir:Patient |
Contributor |
| subject_label | String | 0..1 | No | Language-tagged label of the subject entity | Patient@en |
Contributor |
| predicate_id2 | EntityReference | 1 | Yes | A Health-RI Vocabulary's object property linking subject and object | hriv:hasExactMeaning |
Contributor |
| predicate_modifier | PredicateModifierEnum | 0..1 | No | A modifier for negating the predicate3 | Not |
Contributor |
| object_id | EntityReference | 1 | Yes | Identifier of the object entity | hrio:Person |
Contributor |
| object_label | String | 0..1 | No | Language-tagged label of the object entity | Person@en |
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 mapping4 | 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) | 1..* | Yes | Identifier(s) of mapping reviewer(s) (at least one required) | 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 Initiative |
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 | https://hl7.org/fhir |
Contributor |
| subject_source_version | String | 0..1 | No | Version of the subject source | R4 |
Contributor |
| object_source_version | String | 0..1 | No | Version of the Health-RI ontology used for the mapping | 0.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) |
| comment | String | 0..1 | No | Free-text notes about the mapping | Reviewed for consistency with ontology v0.9.1. |
Contributor |
| replaces | EntityReference(s) | 0..* | No | Indicates that this mapping record replaces another | hrim:1c56bebe |
Contributor |
Identity distinctness (two-person rule)
For every row, the set of author_id values must be disjoint from the set of reviewer_id values. This is validated at publication time (see the Mappings Governance page).
Uniqueness of hriv:hasExactMeaning (current rows)
For any given subject_id, there may be at most one current row with predicate_id = hriv:hasExactMeaning (i.e., not superseded via replaces, and with no predicate_modifier = Not). Rationale: Strategy requires a single exact meaning per concept; "current" follows the append-only supersession model. See the Mappings Governance page for the publication-time check.
Responsible initiative (publisher)
The mapping-set's creator_id and creator_label identify the initiative responsible for making the resource available (i.e., the Health-RI Semantic Interoperability Initiative). SSSOM defines no per-row "curator" slot. The curator's approval is recorded in the publication workflow.
If you negate a predicate
When predicate_modifier is set to Not, include a brief rationale in comment explaining why the negation applies. See the Mapping Governance page's Justification and Evidence section for the policy.
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 CURIE5 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_version – Defaults to the ontology's latest version number. E.g.,
1.0.0. - mapping_date - Defaults to the date the contribution was received via GitHub issue.
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 will review and add it. In the template, field headers are color-coded as follows:
- mandatory with no default have a black background;
- mandatory with a fixed default are purple and pre-filled;
- mandatory with a variable default are purple and not pre-filled;
- optional are green.
Both methods ensure your contribution is reviewed and incorporated into the official Health-RI SSSOM mapping set.
Submission checklist for contributors
Quick check: are your URIs valid?
Before submitting, verify that all HTTP URIs resolve and are well-formed. A simple online check: https://0mg.github.io/tools/uri/
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.
- All
subject_labelandobject_labelfields you provide are language-tagged (e.g.,Patient@en,Patiënt@nl). - Any optional values provided use valid identifiers (e.g., ORCIDs, resolvable URIs, SEMAPV terms).
-
hrimis the prefix for https://w3id.org/health-ri/semantic-interoperability/mappings# ↩ -
Allowed values:
hriv:hasExactMeaning,hriv:hasBroaderMeaningThan,hriv:hasNarrowerMeaningThan. ↩ -
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. ↩ -
W3C CURIE Syntax 1.0 (compact URIs): https://www.w3.org/TR/curie/ ↩