Governance, Lifecycle, and Validation of the Health-RI SSSOM Mapping Set

This page sets the governance, lifecycle, validation, and release policy for the Health-RI SSSOM Mapping Set. It complements the Mapping Set page (schema, field semantics, URIs) and the Semantic Mapping Strategy page (methodology and scope).

Purpose and Scope

This policy defines how the Health-RI SSSOM Mapping Set is governed, validated, versioned, and released so that mappings are trustworthy, reproducible, and easy to discover and reuse in FAIR-aligned infrastructures [1], [18].

Objectives

Enforce clear roles with separation of duties (Mapper, Reviewer, Curator) and independent human approvals (two-person rule).
Run a stateful lifecycle with explicit promotion gates and an append-only supersession model.
Guarantee provenance, reproducibility, and transparent release management.
Align with external standard communities where applicable (e.g., OMOP) and record outcomes [11].

Applicability

Applies to all mapping records proposed for or included in Health-RI mapping artifacts (TSV/TTL) and their metadata as defined on the Mapping Set page.
Covers all submission routes referenced on the Mapping Set page (e.g., issue form or XLSX) and the end-to-end path to publication.

Start stage for mappings

At the current maturity level, mapping work may begin once the relevant HRIO package reaches erv (external review). Our target policy is to prefer mappings to pub (published) packages when possible. Mappings MUST NOT target concepts from packages in int (internal) or irv (internal review). Stage definitions are described in the Ontology Lifecycle and Validation Policy.

Mapping stability depends on HRIO maturity

If the target HRIO package is still in external review, mappings may need revision after publication. Prefer mapping against pub packages when possible, and expect supersession when meanings evolve.

In Scope

Role definitions and two-person rule.
Lifecycle states and promotion gates (Draft → Review → Curation → Published → Superseded).
Validation criteria: schema and completeness, predicate policy (Health-RI Mapping Vocabulary, HRIV), CURIE/URI hygiene, supersession integrity, and temporal/provenance checks.
Versioning and change control (daily-dated releases YYYY-MM-DD, at most one per calendar day; append-only replaces chains; immutable history).
Publication and discovery (stable w3id endpoints; artifacts listed on the Mapping Set page).
External standard community alignment and traceability of submissions.

Out of Scope

Per-row schema, allowed values, justification vocabulary, and field semantics (see the Mapping Set page).
Mapping methodology and domain-specific modeling guidance (see the Semantic Mapping Strategy page).
Tool-specific implementation details beyond what is needed to satisfy the policy.

Expected Outcomes (Conformance)

Every published record:
- Has independent approvals by Reviewer and Curator.
  - The Reviewer approval is recorded per row in SSSOM via reviewer_id.
  - The Curator approval is recorded in the repository publication workflow (in git logs); SSSOM does not define a per-row curator slot.
- Appears in a dated release (YYYY-MM-DD), with release notes summarizing additions, changes, and supersessions.
- Is reachable via stable w3id URIs and traceable via record_id and the replaces chain (as defined and linked on the Mapping Set page).
Historical states are discoverable within the single canonical, append-only artifact via dated entries (see Versioning and Change Control).

Roles and Responsibilities

Mapper
- Acts as the primary owner and creator of the mapping record.
- Analyzes the source standard concept and the target Health-RI Ontology (HRIO) concept in context (definitions, scope notes, relations, etc.), evaluates semantic fit, and selects the appropriate HRIV predicate and, where applicable, a modifier.
- Drafts mapping records with clear comments/rationale for non-obvious choices so mappings are understandable to users.
- Ensures that all mandatory fields defined on the Mapping Set page are present and both semantically and syntactically valid before submission.
- Implements modifications requested by the Reviewer and Curator and resubmits until approval.
Reviewer
- A domain expert or mapper, independent from the author.
- Acknowledges submission, evaluates semantic and syntactical correctness, and either approves for curation or requests changes back to the Mapper.
- Records rationale when non-obvious or when using any negation (predicate_modifier = Not).
Curator
- Performs curation (including format/schema checks, CURIE/URI hygiene, and supersession integrity); may perform minor syntactic fixes when appropriate.
- Optionally serves as a secondary semantic reviewer when needed.
- Decides on approval for publication or requests fixes back to the Mapper.
- Publishes approved mappings.
Separation of duties
- The author and reviewer must be different people (two-person rule).
- Publication requires independent human approvals by the Reviewer and Curator.

Two-person rule is mandatory

The author of a mapping cannot also act as Reviewer or Curator for that same record. If staffing is limited, reschedule publication rather than collapsing roles.

Curator Approval: Workflow, Not Per-Row

Curator approval is captured as workflow evidence (in git logs), not as a per-row SSSOM field. Per-row approval in SSSOM is recorded via reviewer_id.

Lifecycle States and Promotion Gates

The lifecycle follows the flow below.

Promotion gates at a glance

Draft → Review: All mandatory fields present; rationale captured for non-obvious choices.
Review → Curation: Independent Reviewer confirms semantic fit and predicate choice.
Curation → Published: Curator confirms schema, CURIE/URI hygiene, and supersession integrity.
Published → Superseded: New record must reference the prior via replaces (append-only).

Timeboxes (SLA) summary

Reviewer: Concludes within one sprint from receipt; extendable to two sprints with documented justification.
Curator: Provides an outcome (return to Mapper or publish) within one sprint from receipt.
External submission: Initiate community submission within one sprint of publication.

flowchart LR
  subgraph M[Mapper]
    D[Draft mapping]
  end

  subgraph R[Reviewer]
    S[Submission received]
    A{Approve?}
  end

  subgraph C[Curator]
    U[Curation]
    V{Approve?}
    P[Published]
  end

  N{Replaced?}
  X[Superseded]

  D -->|submit for review| S
  S --> A
  A -- yes --> U
  A -. "request changes" .-> D

  U -->|validate format| V
  V -- yes --> P
  V -. "request fixes" .-> D

  P --> N
  N -- yes --> X
  N -- no --> P

  classDef mapper fill:#eef7ff,stroke:#1d4ed8,stroke-width:1px,rx:6,ry:6
  classDef reviewer fill:#fff7ed,stroke:#b45309,stroke-width:1px,rx:6,ry:6
  classDef curator fill:#f0fdf4,stroke:#16a34a,stroke-width:1px,rx:6,ry:6
  classDef superseded fill:#FDE2E2,stroke:#B91C1C,stroke-width:1px,rx:8,ry:8
  classDef decision fill:#FEF3C7,stroke:#CA8A04,stroke-width:1px,rx:6,ry:6

  class D mapper
  class S,A reviewer
  class U,V,P,N curator
  class X superseded
  class A,V,N decision

Lifecycle states

Draft mapping (Mapper)
- Mapper prepares the record with mandatory fields; CURIEs/URIs well-formed; rationale captured for non-obvious choices.
Submission received (Reviewer)
- Reviewer acknowledges intake, evaluates meaning and scope.
- Timeline: Within one sprint from receipt of the mapping from the Mapper, the Reviewer concludes the review; this may be extended to two sprints with documented justification.
- Decision (Approve?)
  - Yes → Curation
  - Request changes → back to Draft
Extensions

Extensions to two sprints are possible when justified.

Reviewer quick-check
- [ ] Predicate choice justified on the concepts' semantics, not label similarity
- [ ] Rationale present for contentious cases or any predicate_modifier = Not
- [ ] Mandatory fields complete per the Mapping Set page
Curation (Curator)
- Curator checks field completeness per the Mapping Set page, CURIE/URI hygiene, and supersession integrity; applies minor syntactic fixes if safe.
- Timeline: Within one sprint from receipt, the Curator analyzes the mapping and provides an outcome (return to Mapper or publish).
- Decision (Approve?)
  - Yes → Published
  - Request fixes → back to Draft
Curator quick-check
- [ ] Required columns
- [ ] Target HRIO stage: object_id belongs to a package in stage erv or pub
- [ ] Allowed HRIV predicates and valid (optional) predicate_modifier
- [ ] CURIE/URI hygiene (resolves with 2xx/3xx where applicable)
- [ ] replaces points to an existing record
- [ ] mapping_date ≤ publication_date
- [ ] Uniqueness (Exact Meaning): For each subject_id, ensure no more than one current row has predicate_id = hriv:hasExactMeaning and no predicate_modifier = Not (use the replaces chain to determine which row is current).
- [ ] Per-record identifiers: record_id and any replaces URIs use the hrim prefix¹.
Published (Curator)
- Merged to main, included in a dated release, and exposed via stable w3id endpoints listed on the Mapping Set page.
Superseded
- When Replaced? is Yes, a newer record references the prior via replaces. Append-only: older records remain in the canonical artifact; consumers should follow the latest in the replaces chain.

How to resolve to the current mapping

When multiple rows exist for the same source-target pair, follow the latest entry in the replaces chain. Do not assume the highest record_id is the current mapping.

Versioning and Change Control

Release cadence: At most one release per calendar day, versioned as YYYY-MM-DD.
Append-only records: No in-place edits to published rows. Corrections create a new record that references the prior via replaces.
Reproducibility: The canonical artifact is a single append-only TSV/TTL; prior states are recoverable via dated rows. Current validity can be assessed using replaces chains.

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.

No in-place edits to published rows

Fixes must be new records that point to the prior one via replaces. Editing a published row is not possible, as it would break reproducibility and the audit trail.

Semantic Requirements

Avoid false agreement (labels are not semantics)

Similar labels, codes, or even OWL axioms across artifacts are not sufficient evidence of shared meaning. Predicate selection must be justified using definitions, scope notes, and modeled constraints—not string similarity [19], [22].

Normative, per-row schema constraints (e.g., allowed predicates, label language tags, justification vocabulary) are defined on the Mapping Set page. This section provides usage guidance only.

Justification and Evidence

Draft your justification before submitting

The HRIO Mapping Assistant can help you draft:

candidate HRIO target labels
a recommended HRIV predicate_id with a confidence estimate
short evidence snippets you can paste into comment as your justification

Keep the final decision human-reviewed and aligned with governance (e.g., two-person rule and promotion gates). Your comment should still capture definitional/semantic reasoning (not label similarity).

Open HRIO Mapping Assistant

Set mapping_justification to the appropriate method indicator. By default (and currently the only generally acceptable value) it is semapv:ManualMappingCuration (a curator-approved alternative may be used when explicitly evaluated). This field records the method/rationale category for how the mapping was produced, not the semantic relation itself.
Capture the concrete reasoning for your choice of HRIV predicate_id (e.g., hriv:hasExactMeaning, hriv:hasBroaderMeaningThan, hriv:hasNarrowerMeaningThan) in the comment field. When justifying, use definitional/semantic arguments (notes, formal definitions) over label similarity [22].
When using a negation, set predicate_modifier to Not (its only valid value) and add a brief rationale in comment.
For borderline hierarchical mappings, add a brief rationale in comment explaining why you selected broader or narrower.

What to include as evidence in comment

When a mapping is non-obvious, add short evidence pointers in comment (e.g., definition excerpts, scope-note references, or URLs to the relevant standard/ontology documentation). Keep it concise but sufficient for an independent reviewer to reproduce the decision [22].

Validation

Reviewer (independent from author):
- Apply the predicate selection policy in Semantic Requirements; base decisions on definitions, scope notes, and modeled relations (not label similarity).
- Ensure rationale is recorded for contentious cases or any Not.
- Approve or request changes (back to Draft).
Curator:
- Schema & completeness: required columns present; datatypes valid; unique record_id; valid prefixes (per the Mapping Set page).
- Predicate policy: conformance to allowed HRIV predicates and modifier rules (per the Mapping Set page).
- URI hygiene: HTTP URIs well-formed and (where applicable) dereference with a 2xx/3xx response.
- Supersession integrity: replaces points to an existing record.
- Temporal/provenance consistency: mapping_date ≤ publication_date.
- Approve for Published or request fixes (back to Draft).
- Identity distinctness: verify that the set of author_id values is disjoint from the set of reviewer_id values within each row (enforcing two-person rule).

Publication and Discovery

Only mappings that have passed Reviewer and Curator approvals are published.
Published artifacts and stable URIs are exactly those listed on the Mapping Set page.

For submission methods (issue form/XLSX) and the contributor checklist, see the Mapping Set page ("How to Contribute").

External standard community alignment

When a source or target standard maintains an official mapping registry or acceptance process (e.g., OHDSI/OMOP), Health-RI shall:

Submit after publication: Within one sprint of publication, notify/submit the mapping(s) to the standard's community channel or registry.
Provide traceable facts: Include the Health-RI release date (publication_date), affected record_id(s), chosen HRIV predicate (predicate_id), and mapping_justification.
Record the submission: Add the submission URL or ticket ID in release notes; optionally place a per-row link in the comment field.
Handle outcomes via supersession: If the external review requests changes, publish a new record that supersedes the previous one using replaces (append-only), with a short rationale [11].

Submission SLA

Submissions to external registries (e.g., OHDSI/OMOP) must be initiated within one sprint of publication.

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

[11]: Observational Health Data Sciences and Informatics. (2014). OMOP Common Data Model. 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. (Ed.). (1998). Formal Ontology in Information Systems: Proceedings of the 1st International Conference (Trento, Italy, June 6–8, 1998). 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

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