Skip to content

The Health-RI SSSOM Mapping Set Schema

One of the key deliverables of the Health-RI Semantic Interoperability Initiative was a SSSOM mapping set. This mapping set was manually curated, reflecting the efforts of both the dedicated mapping team and external collaborators. In line with work that treats mappings as first-class artifacts separating meaning (data element concepts) from representation, Health-RI used SSSOM to support semantic traceability and reuse across standards (e.g., FHIR [8], OMOP [11], openEHR [9]) [29]. For the initiative-level conceptual background (including our definition of semantic traceability), see our academic paper [30]. For the mapping-specific 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.

Archival status

The Health-RI Semantic Interoperability Initiative has been discontinued. This page is retained as the schema reference for the final published mapping set. The contribution, review, curation, and publication workflow described below is historical and is no longer operated by Health-RI under this initiative.

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, supporting long-term findability and reuse in FAIR-aligned infrastructures [1], [18]:

  • 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 were dated YYYY-MM-DD (at most one per calendar day) and records were append-only via replaces.

For the lifecycle states, approvals, and publication policy used during active development, 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

Archived HRIO Mapping Assistant

The HRIO Mapping Assistant may remain accessible as an archival drafting aid. It is not maintained and its outputs do not enter an active Health-RI contribution, review, curation, or release workflow.

  • It proposes HRIO candidate labels, a single HRIV predicate_id, confidence, and evidence snippets.
  • Evidence snippets can be used in comment to document why the predicate fits (definition/scope reasoning).
  • If the assistant provides an OntoUML type/stereotype, it can be copied into object_category when appropriate.
  • The final published workflow used semapv:ManualMappingCuration as the default mapping_justification unless a curator explicitly approved an alternative.

Important: HRIV predicates express meaning-level links and must not be interpreted as OWL equivalence/subsumption.

Open HRIO Mapping Assistant

SSSOM-based mapping sets have been used to operationalize semantic traceability by enabling meaning-level correspondences across heterogeneous standards while preserving separations between concepts and representations [29].

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 Mapping Vocabulary (HRIV) 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 (HRIO) 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 was 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 was 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.

HRIV predicates are not OWL equivalence/subsumption

hriv:hasExactMeaning, hriv:hasBroaderMeaningThan, and hriv:hasNarrowerMeaningThan express meaning-level links for traceability and reuse. They must not be interpreted as OWL class axioms (e.g., owl:equivalentClass, rdfs:subClassOf) or as evidence of class identity across standards. [22], [19]

Record versions precisely for reproducibility

When available, always provide an exact source release identifier in subject_source_version and object_source_version (not just a major family like "R4"). This makes it clear which standard/ontology release your mapping was evaluated against. [8], [9], [11]

Responsibility Legend

The following legend explains who was responsible for providing or assigning each field in the schema, clarifying whether values came from contributors, curators, or were system-generated:

  • Contributor – Was provided in PRs.
  • Curator – Was added manually by Health-RI curators.
  • Contributor (or Default) – Contributor provided this or the system assigned a default.
  • System (Fixed) – Was always set to a fixed value.
  • System (Generated) – Was automatically assigned at publication time.

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

The publication workflow assigned predefined default values when contributors did not provide them:

  • mapping_justification – Defaulted to semapv:ManualMappingCuration.
  • license – Defaulted to https://creativecommons.org/licenses/by/4.0/.
  • object_source_version – Defaulted to HRIO's latest version number at curation time. E.g., 1.0.0.
  • mapping_date - Defaulted to the date the contribution was received via GitHub issue.

Defaults were resolved to concrete values

Defaults such as object_source_version and mapping_date were resolved to specific values at curation time and stored in the record. They are not interpreted as "floating latest" values.

Historical Contribution Process

During active development, contributions to expand and refine the mapping set were accepted through two routes. These routes are documented for provenance only; the discontinued initiative no longer reviews or integrates new mapping submissions.

Preferred route: issue form

Contributors used the SSSOM mapping issue form to submit a single mapping row. Required fields were completed in the form and Health-RI curators reviewed eligible submissions before integration.

Alternative route: Excel template

Contributors could use the XLSX template and enter:

  • the mapping row(s) in the mappings sheet, and
  • all CURIE prefix bindings in the prefix sheet.

The completed file was attached to a GitHub issue for review.

CURIE prefixes must be declared consistently

If a mapping uses a new CURIE prefix, it should declare the official namespace URI so the identifier remains resolvable and reproducible.

In the template, field headers were 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.

Historical submission checklist

The following checks were used for contributed mappings:

  • All mandatory contributor fields were present and correctly formatted.
  • The object_id was an HRIO concept in a package at stage erv or pub (mappings to int or irv packages were not accepted).
  • All supplied subject_label and object_label fields were language-tagged (e.g., Patient@en, Patiënt@nl).
  • Optional values used valid identifiers (e.g., ORCID IDs, resolvable URIs, SEMAPV terms).

References

[1] Wilkinson, M. D., et al. (2016). The FAIR guiding principles for scientific data management and stewardship. Scientific Data, 3(1), 160018. https://doi.org/10.1038/sdata.2016.18

[8] HL7 International. (2023). FHIR Release 5. Retrieved December 1, 2025, from https://www.hl7.org/fhir/R5/

[9] openEHR Foundation. (2020). Architecture overview. Retrieved December 1, 2025, from https://specifications.openehr.org/releases/BASE/latest/architecture_overview.html

[11] Observational Health Data Sciences and Informatics. (2014). OMOP Common Data Model. Retrieved December 1, 2025, from https://ohdsi.github.io/CommonDataModel/

[18] Guizzardi, G. (2020). Ontology, ontologies and the "I" of FAIR. Data Intelligence, 2(1–2), 181–191. https://doi.org/10.1162/dint_a_00040

[19] Guarino, N. (1998). Formal ontology in information systems: Proceedings of the 1st International Conference (FOIS '98), June 6–8, 1998, Trento, Italy (1st ed.). IOS Press.

[22] Guizzardi, G., & Guarino, N. (2024). Explanation, semantics, and ontology. Data & Knowledge Engineering, 153, 102325. https://doi.org/10.1016/j.datak.2024.102325

[29] Zhang, S., Smits, A., Brochhausen, M., Solbrig, H. E., & Wilkinson, M. D. (2021). Operationalizing the ISO/IEC 11179 metadata registry model for semantic findability, interoperability and reuse of complex data elements. International Journal on Semantic Web and Information Systems, 17(4), 1–33. https://doi.org/10.4018/IJSWIS.2021100101

[30] Barcelos, P. P. F., van Ulzen, N., Groeneveld, R., Konrad, A., Khalid, Q., Zhang, S., Trompert, A., & Vos, J. (n.d.). Enabling Semantic Traceability in Health Data: The Health-RI Semantic Interoperability Initiative (manuscript approved at SWAT4HCLS 2026, v1.1.1). Download link..

  1. hrim is the prefix for https://w3id.org/health-ri/semantic-interoperability/mappings# ↩

  2. Allowed values: hriv:hasExactMeaning, hriv:hasBroaderMeaningThan, hriv:hasNarrowerMeaningThan. ↩

  3. May either be set to Not (its only valid value) or left empty. It is used specifically to express a negated mapping predicate. ↩

  4. Currently, the only acceptable value for mapping_justification is semapv:ManualMappingCuration, or a comparable alternative subject to curator evaluation. This constraint is essential for maintaining the necessary semantic alignment. ↩

  5. W3C CURIE Syntax 1.0 (compact URIs): https://www.w3.org/TR/curie/ ↩