Support linked mapping-only sources for CIEL SNOMED-CT and ICD-11 mappings

Abierto
  • ¿Algo no está bien?
#2,874 3 comentarios 0 reacciones 1 asignado Ver en GitHub

@filiperochalopes ya está trabajando en esto.

Desde el 4/10/2026.

Evaluación

Este issue todavía no se ha evaluado.

Descripción

signal/has-dependencies signal/high-risk signal/large-scope stage/triaged type/feature

User story

As a CIEL terminologist and release maintainer, I want CIEL's SNOMED-CT and ICD-11 mappings stored in separate mapping-only sources that still behave as part of CIEL, so we meet licensing constraints without losing the concept view, API results, bundles, or OpenMRS-compatible exports we rely on today.

Use case

A curator adds a SNOMED-CT SAME-AS mapping to CIEL concept 1234 in CIEL Lab. The mapping is stored in /orgs/CIEL/sources/map-SNOMED-CT/, but OCL Web, the OCL API (includeMappings, /concepts/1234/mappings/, $cascade) and the next CIEL release export still show it together with the concept's other mappings, and the OpenMRS dump still contains it.

Requirements

  • Move CIEL mappings whose target is /orgs/IHTSDO/sources/SNOMED-CT/ or /orgs/WHO/sources/ICD-11-WHO/ out of /orgs/CIEL/sources/CIEL/ into dedicated mapping-only sources.
    • SNOMED-CT → /orgs/CIEL/sources/map-SNOMED-CT/.
    • ICD-11 → a mapping source following the same convention (name to be confirmed).
    • Mapping-only sources contain mappings only; from_concept_url keeps pointing at CIEL concepts.
  • Add a CIEL source configuration (oclapi2) that declares linked mapping sources per target source, e.g. /orgs/IHTSDO/sources/SNOMED-CT/ → /orgs/CIEL/sources/map-SNOMED-CT/.
  • Reads (oclapi2): with the configuration in place, CIEL concept responses return linked mappings as they do today.
    • Concept detail with includeMappings / includeInverseMappings.
    • /concepts/{id}/mappings/.
    • Concept search indexing of mapped codes.
    • Linked mappings are returned only when the caller has view access to the linked mapping source.
  • Writes (oclapi2): inline mappings sent in a CIEL concept create/update whose target matches a configured target source are persisted in the linked mapping source, not in CIEL.
  • Bundles (oclapi2): $cascade and collection reference cascade on a CIEL source version include mappings from the linked mapping sources.
  • Versioning: a CIEL source version must be resolvable to the matching versions of its linked mapping sources, so a released version is reproducible.
  • Exports: keep a way to produce the OpenMRS-compatible outputs we produce today.
    • OpenMRS SQL dump (CIEL Lab release) contains the same SNOMED-CT and ICD-11 concept_reference_map rows as before the split.
    • OCL export / subscription consumed by openmrs-module-openconceptlab (single subscription URL) still delivers CIEL concepts with their linked mappings for authorized consumers.
    • A CIEL-only export without the linked mappings remains possible.
  • CIEL Lab (ciel-lab-v2) treats CIEL plus its linked mapping sources as one logical source.
    • Configuration for linked mapping sources next to OCL_CIEL_SOURCE_URI.
    • HEAD mirror, staged changes and QA include linked mappings.
    • A mapping write to a linked mapping source re-syncs the from-concept in the HEAD mirror.
    • Release creates the linked mapping source versions together with the CIEL version and builds the SQL dump from the combined content.
  • Migration preserves mapping identity and history.
    • Preserve external_id (used as OpenMRS concept_reference_map.uuid), map type, retired state and extras.
    • Existing released CIEL versions remain unchanged.
  • Decide and document before implementation:
    • Exact licensing constraint: who may view/export SNOMED-CT and ICD-11 mappings (public access of the mapping sources and of combined exports).
    • Where the configuration lives on the Source model (new field vs. existing attribute) and its API contract.
    • How CIEL and mapping source versions are paired (same version id vs. recorded pairing).
    • Delivery shape for OpenMRS: combined source export, collection composing CIEL + mapping sources, or CIEL Lab merge.
    • Whether mapping ids (mnemonics) are kept or reassigned in the new sources.

Acceptance criteria

  • Given CIEL has a linked mapping source for SNOMED-CT, when a user with access requests a CIEL concept with includeMappings=true, then its SNOMED-CT mappings stored in map-SNOMED-CT are returned with the same fields as today.
  • Given a user without view access to map-SNOMED-CT, when they request the same concept, then SNOMED-CT mappings are not returned and no error is raised.
  • Given a CIEL concept update containing a new SNOMED-CT mapping, when it is saved, then the mapping is created in map-SNOMED-CT and no SNOMED-CT mapping is created in /orgs/CIEL/sources/CIEL/.
  • Given a CIEL source version with paired mapping source versions, when $cascade runs on a CIEL concept, then the bundle includes its linked SNOMED-CT and ICD-11 mappings.
  • Given the split is applied, when CIEL Lab builds the OpenMRS SQL dump for a release, then SNOMED-CT and ICD-11 concept_reference_map rows match a pre-split dump of the same content, including uuids.
  • Given an OpenMRS instance subscribed to the CIEL delivery URL, when it imports the next release, then SNOMED-CT and ICD-11 mappings are imported as before.
  • Given the migration ran, then no SNOMED-CT or ICD-11 mappings remain in /orgs/CIEL/sources/CIEL/ HEAD and previously released CIEL versions are unchanged.
  • Given a mapping is saved in a linked mapping source through CIEL Lab, then the HEAD mirror and staged changes show it on the from-concept.
  • Open decisions above are answered and recorded before implementation starts.

More details (collapsible)

Current behavior and impacted code

Context: static, read-only inspection of oclapi2 (master 573aa852), ciel-lab-v2 (main e8ddab4) and openmrs-module-openconceptlab (b8a9117). Not reproduced on a live OCL.

oclapi2 — what already works:

  • A mapping can belong to one source and start from a concept in another: from_source / from_source_url (core/mappings/models.py).
  • Collection-scoped concept mappings come from the expansion, not the parent source (core/concepts/models.py, get_*_mappings_for_collection), so a collection composing CIEL + mapping sources already returns them.

oclapi2 — what blocks the split today:

  • Concept mapping reads filter Mapping.parent_id == concept.parent_id (core/concepts/models.py, __get_mappings_from_relation). Used by concept serializers, ConceptMappingsView and ES indexing (core/concepts/documents.py).
  • Inline concept mappings are always created with parent_id = concept.parent_id (core/concepts/models.py, _create_mapping_from_self).
  • Source-version cascade reads repo_version.mappings only (core/concepts/models.py, cascaded_resources_*_for_source_version); collection reference cascade resolves to the concept's own source version.
  • Source export serializes one source version (core/common/tasks.py, export_source).
  • Source has content_type (incl. supplement) and collection_reference, but no field for linked mapping sources.

ciel-lab-v2 — single-source assumptions:

  • One OCL_CIEL_SOURCE_URI drives release, HEAD refresh, staged changes, write classification, MCP tools and search (api/src/infrastructure/settings.py).
  • Concept Editor sends mappings inline in the CIEL concept payload (web/src/services/oclApiWriteRequests.ts).
  • HEAD mirror sync after a mapping write happens only for the CIEL source (api/src/services/ocl_write_intent.py).
  • Release creates, releases and exports only the CIEL version (api/src/services/ocl_release_service.py).
  • The OpenMRS SQL dump reads one export.json and uses mapping external_id as concept_reference_map.uuid; target resolved by to_source_name (SNOMED-CT, ICD-11-WHO) (api/src/tasks/build_release_sql.py, api/src/services/openmrs_dump.py).

openmrs-module-openconceptlab:

  • Imports from a single subscription URL (OpenConceptLabConstants.GP_SUBSCRIPTION_URL).

Architecture diagram: see the first comment.

Lenguaje dominante
Sin datos de lenguaje
Estrellas
4
Forks
2
Merge medio
2 h 12 min
PR fusionados (30 d)
1

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de OpenConceptLab/ocl_issues

Todos los issues de OpenConceptLab/ocl_issues

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.