From 49b3d72cb2a19d99752af1260beac7c23a85b407 Mon Sep 17 00:00:00 2001 From: "Dr. B. M. Riazul Islam" Date: Sun, 8 Mar 2026 14:40:19 +0600 Subject: [PATCH] Prepare 0.3.0: ICD-11 MMS integration --- input/bd.fhir.core.xml | 2 +- input/fsh/BDConditionProfile.fsh | 8 - .../fsh/extensions/icd11ClusterExpression.fsh | 68 +++++ input/fsh/immunization.json | 39 --- .../namingSystems/ICD11MMSNamingSystem.fsh | 63 +++++ input/fsh/profile/BDConditionProfile.fsh | 65 +++++ .../valueSets/BDConditionICD11DiagnosisVS.fsh | 62 +++++ input/fsh/valueSets/BDConditionICD11VS.fsh | 6 - input/includes/menu.xml | 3 + input/package-list.json | 14 +- input/pagecontent/icd11.md | 244 ++++++++++++++++++ input/pagecontent/spec.md | 136 +++++++++- package-feed.xml | 33 --- package-list.backup | 23 -- package-list.json | 14 +- publication-request.backup | 12 - sushi-config.yaml | 2 +- 17 files changed, 662 insertions(+), 132 deletions(-) delete mode 100644 input/fsh/BDConditionProfile.fsh create mode 100644 input/fsh/extensions/icd11ClusterExpression.fsh delete mode 100644 input/fsh/immunization.json create mode 100644 input/fsh/namingSystems/ICD11MMSNamingSystem.fsh create mode 100644 input/fsh/profile/BDConditionProfile.fsh create mode 100644 input/fsh/valueSets/BDConditionICD11DiagnosisVS.fsh delete mode 100644 input/fsh/valueSets/BDConditionICD11VS.fsh create mode 100644 input/pagecontent/icd11.md delete mode 100644 package-feed.xml delete mode 100644 package-list.backup delete mode 100644 publication-request.backup diff --git a/input/bd.fhir.core.xml b/input/bd.fhir.core.xml index 78a4e14..117fc63 100644 --- a/input/bd.fhir.core.xml +++ b/input/bd.fhir.core.xml @@ -13,7 +13,7 @@ --> - + <status value="active"/> diff --git a/input/fsh/BDConditionProfile.fsh b/input/fsh/BDConditionProfile.fsh deleted file mode 100644 index 5b95a9f..0000000 --- a/input/fsh/BDConditionProfile.fsh +++ /dev/null @@ -1,8 +0,0 @@ -Profile: BDConditionProfile -Parent: Condition -Id: bd-condition -Title: "ICD 11" -Description: "Condition coded with ICD-11" - -* code 1..1 MS -* code from BDConditionICD11VS (preferred) diff --git a/input/fsh/extensions/icd11ClusterExpression.fsh b/input/fsh/extensions/icd11ClusterExpression.fsh new file mode 100644 index 0000000..b9f4092 --- /dev/null +++ b/input/fsh/extensions/icd11ClusterExpression.fsh @@ -0,0 +1,68 @@ +// ============================================================ +// icd11ClusterExpression.fsh +// Extension for ICD-11 postcoordinated cluster expressions +// Context: Coding (broad — usable across all ICD-11 coded elements) +// ============================================================ + +Extension: ICD11ClusterExpression +Id: icd11-cluster-expression +Title: "ICD-11 Cluster Expression" +Description: """ +Carries a postcoordinated ICD-11 cluster expression as a single string +on a Coding element where the stem code alone is insufficient to fully +represent the clinical concept. + +A cluster expression combines a stem code with one or more satellite +codes using the & operator (combination) or / operator (specificity). +Example: NC72.Z&XK8G&XJ7ZH&XJ7YM + - NC72.Z — stem: Fracture of femur, unspecified + - XK8G — satellite: laterality + - XJ7ZH — satellite: fracture subtype + - XJ7YM — satellite: fracture open or closed + +Usage rules: + - SHALL only be present when the expression contains at least one + satellite code joined by & or / operators. + - Single stem codes SHALL be represented in Coding.code only and + validated via OCL $validate-code. The cluster validator at + https://icd11.dghs.gov.bd/cluster/validate explicitly rejects + stem-only expressions. + - The stem code in Coding.code SHALL match the leading stem code + in this expression string. + - Satellite codes in the cluster expression are exempt from the + Diagnosis/Finding class restriction that applies to stem codes + in Condition.code. + - Cluster expressions SHALL be validated against the Bangladesh + ICD-11 Cluster Validator at https://icd11.dghs.gov.bd/cluster/validate + prior to submission to the HIE. + +Cluster validator endpoint: + POST https://icd11.dghs.gov.bd/cluster/validate + Body: { "expression": "NC72.Z&XK8G&XJ7ZH&XJ7YM" } + +This extension is not MustSupport and is not mandatory. It is present +only when postcoordination is clinically required. Cluster expressions +are typically sourced from the WHO Electronic Coding Tool (ECT) at the +point of care. +""" + +* ^url = "https://fhir.dghs.gov.bd/core/StructureDefinition/icd11-cluster-expression" +* ^status = #active +* ^experimental = false +* ^publisher = "Directorate General of Health Services (DGHS), MoHFW, Bangladesh" +* ^contact.name = "DGHS Health Informatics Unit" +* ^contact.telecom.system = #url +* ^contact.telecom.value = "https://dghs.gov.bd" +* ^jurisdiction = urn:iso:std:iso:3166#BD "Bangladesh" +* ^context[+].type = #element +* ^context[=].expression = "Coding" + +* value[x] only string +* valueString 1..1 +* valueString ^short = "ICD-11 postcoordinated cluster expression string" +* valueString ^definition = """ +The full postcoordinated cluster expression, including the stem code and +all satellite codes joined by & or / operators. Example: +NC72.Z&XK8G&XJ7ZH&XJ7YM. The stem code in this string SHALL match +Coding.code on the parent Coding element. +""" \ No newline at end of file diff --git a/input/fsh/immunization.json b/input/fsh/immunization.json deleted file mode 100644 index fdc5961..0000000 --- a/input/fsh/immunization.json +++ /dev/null @@ -1,39 +0,0 @@ -{ - "resourceType": "StructureDefinition", -<<<<<<< HEAD - "id": "bd-Immunization", - "url": "http://example.org/StructureDefinition/bd-Immunization", - "version": "1.0.0", - "name": "BDImmunizationProfile", - "title": "Immunization Profile for Bangladesh", - "description": "Bangladesh Immunization Profile", -======= - "id": "bd-immunization", - "url": "https://fhir.dghs.gov.bd/core/identifier/bd-immunization", - "version": "1.0.0", - "name": "BDImmunizationProfile", - "title": "Patient Immunization Profile for Bangladesh", - "description": "Patients Immunization Bangladesh Standard", ->>>>>>> 1c45affa520e64b3b9efc307d9116ff138171fa5 - "fhirVersion": "4.0.1", - "kind": "resource", - "abstract": false, - "type": "Immunization", - "baseDefinition": "http://hl7.org/fhir/StructureDefinition/Immunization", - "derivation": "constraint", - "differential": { - "element": [ - { - "id": "Immunization.identifier", - "path": "Immunization.identifier", -<<<<<<< HEAD - "short": "Unique identifier", -======= - "short": "Identifier", ->>>>>>> 1c45affa520e64b3b9efc307d9116ff138171fa5 - "definition": "Unique identifier for the vaccination event", - "min": 1 - } - ] - } -} \ No newline at end of file diff --git a/input/fsh/namingSystems/ICD11MMSNamingSystem.fsh b/input/fsh/namingSystems/ICD11MMSNamingSystem.fsh new file mode 100644 index 0000000..96f62da --- /dev/null +++ b/input/fsh/namingSystems/ICD11MMSNamingSystem.fsh @@ -0,0 +1,63 @@ +// ============================================================ +// ICD11MMSNamingSystem.fsh +// NamingSystem for ICD-11 MMS in the Bangladesh national context +// Canonical authority: WHO +// National resolver: OCL at https://tr.ocl.dghs.gov.bd +// ============================================================ + +Instance: icd11-mms-bd +InstanceOf: NamingSystem +Usage: #definition +Title: "ICD-11 MMS NamingSystem — Bangladesh" +Description: """ +Declares the ICD-11 Mortality and Morbidity Statistics (MMS) coding system +as a known and supported terminology within the Bangladesh national health +information infrastructure. + +Canonical system URI: http://id.who.int/icd/release/11/mms +Canonical authority: World Health Organization (WHO) + +Preferred code form: short stem codes (e.g. 1A00, NC72.Z). +Linearization URIs are not used as code identifiers in this IG. + +National terminology resolver (OCL): + https://tr.ocl.dghs.gov.bd + +Supported OCL operations (use `system=` parameter, not `url=`): + - $validate-code: https://tr.ocl.dghs.gov.bd/api/fhir/CodeSystem/$validate-code + ?system=http://id.who.int/icd/release/11/mms&code={code} + - $lookup: https://tr.ocl.dghs.gov.bd/api/fhir/CodeSystem/$lookup + ?system=http://id.who.int/icd/release/11/mms&code={code} + +$expand is not supported — known OCL limitation. + +Version 2025-01 is active in the national OCL instance with 36,941 +imported concepts. The OCL resolver is an internal national service; +vendors do not interact with it directly. All vendor submissions are +validated at the HIE boundary via the Bangladesh ICD-11 Cluster Validator +at https://icd11.dghs.gov.bd/cluster/validate. +""" + +* name = "ICD11MMSBangladesh" +* status = #active +* kind = #codesystem +* date = "2025-01-01" +* publisher = "Directorate General of Health Services (DGHS), MoHFW, Bangladesh" +* contact.name = "DGHS Health Informatics Unit" +* contact.telecom.system = #url +* contact.telecom.value = "https://dghs.gov.bd" +* jurisdiction = urn:iso:std:iso:3166#BD "Bangladesh" +* responsible = "World Health Organization (WHO)" + +// Primary identifier — canonical system URI (WHO authority) +* uniqueId[+].type = #uri +* uniqueId[=].value = "http://id.who.int/icd/release/11/mms" +* uniqueId[=].preferred = true +* uniqueId[=].comment = "Canonical ICD-11 MMS system URI. Canonical authority is WHO." +* uniqueId[=].period.start = "2025-01-01" + +// Secondary identifier — national OCL source locator (machine-discoverable, not canonical) +* uniqueId[+].type = #uri +* uniqueId[=].value = "https://tr.ocl.dghs.gov.bd/orgs/MoHFW/sources/ICD-11-MMS/" +* uniqueId[=].preferred = false +* uniqueId[=].comment = "National terminology resolver — Bangladesh OCL instance. Not the canonical system URI." \ No newline at end of file diff --git a/input/fsh/profile/BDConditionProfile.fsh b/input/fsh/profile/BDConditionProfile.fsh new file mode 100644 index 0000000..da10f1f --- /dev/null +++ b/input/fsh/profile/BDConditionProfile.fsh @@ -0,0 +1,65 @@ +// ============================================================ +// BDConditionProfile.fsh +// BD-Core Condition profile with mandatory ICD-11 MMS stem slice +// Binding: Diagnosis and Finding class concepts only +// Runtime enforcement via OCL ValueSet $validate-code +// ============================================================ + +Profile: BDConditionProfile +Parent: Condition +Id: bd-condition +Title: "BD Core Condition Profile (ICD-11)" +Description: """ +Condition resource coded with ICD-11 MMS, restricted to Diagnosis and +Finding class concepts. Defined in the Bangladesh Core FHIR Implementation +Guide (BD-Core-FHIR-IG) published by DGHS/MoHFW. +""" + +* code 1..1 MS +* code from bd-condition-icd11-diagnosis-valueset (preferred) +* code ^comment = """ +Condition.code SHALL contain at least one coding conforming to the +coding[stem] slice with system = http://id.who.int/icd/release/11/mms. + +Stem code rules: + - The stem code SHALL be a Diagnosis or Finding class ICD-11 MMS concept. + - This restriction is enforced at runtime via OCL ValueSet $validate-code + against the Bangladesh ICD-11 MMS Condition ValueSet. + - Stem-only codes SHALL be validated via OCL $validate-code. + - Substance, Organism, Device, Anatomy, and Misc class concepts SHALL NOT + appear as standalone stem codes in Condition.code. + +Cluster expression rules: + - When a concept requires postcoordination, the full cluster expression + SHALL be carried in the icd11-cluster-expression extension on coding[stem]. + - The icd11-cluster-expression extension SHALL only be present when the + expression contains at least one satellite code joined by & or / operators. + - Satellite codes in the cluster expression are exempt from the + Diagnosis/Finding class restriction. + - Cluster expressions SHALL be validated against the Bangladesh ICD-11 + Cluster Validator at https://icd11.dghs.gov.bd/cluster/validate + prior to submission to the HIE. + +Additional local codings are permitted alongside the mandatory ICD-11 stem +(slicing is open). Cluster expressions are typically sourced from the WHO +Electronic Coding Tool (ECT) at the point of care. +""" + +* code.coding ^slicing.discriminator.type = #value +* code.coding ^slicing.discriminator.path = "system" +* code.coding ^slicing.rules = #open +* code.coding ^slicing.description = "Slice requiring exactly one ICD-11 MMS stem code. Additional local codings permitted." + +* code.coding contains stem 1..1 +* code.coding[stem] ^short = "Mandatory ICD-11 MMS stem code" +* code.coding[stem] ^definition = """ +Exactly one ICD-11 MMS stem code is required. The stem code SHALL be a +Diagnosis or Finding class concept. When the condition requires +postcoordination, the full cluster expression is carried in the +icd11-cluster-expression extension on this coding element. +""" +* code.coding[stem].system 1..1 +* code.coding[stem].system = "http://id.who.int/icd/release/11/mms" (exactly) +* code.coding[stem].code 1..1 +* code.coding[stem].extension contains + https://fhir.dghs.gov.bd/core/StructureDefinition/icd11-cluster-expression named clusterExpression 0..1 \ No newline at end of file diff --git a/input/fsh/valueSets/BDConditionICD11DiagnosisVS.fsh b/input/fsh/valueSets/BDConditionICD11DiagnosisVS.fsh new file mode 100644 index 0000000..78d8302 --- /dev/null +++ b/input/fsh/valueSets/BDConditionICD11DiagnosisVS.fsh @@ -0,0 +1,62 @@ +// ============================================================ +// BDConditionICD11DiagnosisVS.fsh +// ICD-11 MMS ValueSet restricted to Diagnosis and Finding classes +// Binding target for Condition.code in BDConditionProfile +// Empty stub — runtime enforcement via OCL $validate-code +// $expand not available — suppressed in sushi-config.yaml +// ============================================================ + +ValueSet: BDConditionICD11DiagnosisVS +Id: bd-condition-icd11-diagnosis-valueset +Title: "Bangladesh ICD-11 MMS Condition ValueSet (Diagnosis and Finding)" +Description: """ +ICD-11 MMS concepts restricted to the Diagnosis (14,071) and Finding (5,590) +concept classes, totalling 19,661 concepts as of version 2025-01. + +This ValueSet is the binding target for Condition.code in the BD-Core +Condition profile. Substance, Organism, Device, Anatomy, and Misc class +concepts are excluded and SHALL NOT appear as standalone stem codes in +Condition.code. This restriction applies to stem codes only — satellite +codes carried in the icd11-cluster-expression extension are exempt. + +This ValueSet is an empty stub. No compose block is declared because +$expand is not supported by the national OCL terminology server and +no machine-executable filter for concept_class is available at the +IG layer. The compose would be nominal only and is omitted to avoid +misrepresenting machine-executable semantics. + +The ValueSet is hosted in OCL as a collection with 19,661 explicit +concept references (Diagnosis and Finding classes only). Runtime +enforcement is via OCL ValueSet $validate-code: + + GET https://tr.ocl.dghs.gov.bd/api/fhir/ValueSet/$validate-code + ?url=https://fhir.dghs.gov.bd/core/ValueSet/bd-condition-icd11-diagnosis-valueset + &system=http://id.who.int/icd/release/11/mms + &code={code} + +Confirmed behaviour: + - Diagnosis class (e.g. 1A00): accepted + - Finding class: accepted + - Device class (e.g. XD7EB1): rejected + - Substance class (e.g. XM6RB2): rejected + +At the HAPI FHIR layer, enforcement is via RemoteTerminologyServiceValidationSupport +configured to call OCL. HAPI FHIR deployment is a known gap to be closed +before vendor onboarding. + +VERSION UPGRADES: + Upgrading to a new ICD-11 MMS release requires re-running + populate_condition_valueset.py. Automated via version_upgrade.py. +""" + +* ^url = "https://fhir.dghs.gov.bd/core/ValueSet/bd-condition-icd11-diagnosis-valueset" +* ^status = #active +* ^experimental = false +* ^version = "2025-01" +* ^publisher = "Directorate General of Health Services (DGHS), MoHFW, Bangladesh" +* ^contact.name = "DGHS Health Informatics Unit" +* ^contact.telecom.system = #url +* ^contact.telecom.value = "https://dghs.gov.bd" +* ^jurisdiction = urn:iso:std:iso:3166#BD "Bangladesh" +* ^copyright = "ICD-11 is copyright © World Health Organization. Used under licence." +* ^immutable = false \ No newline at end of file diff --git a/input/fsh/valueSets/BDConditionICD11VS.fsh b/input/fsh/valueSets/BDConditionICD11VS.fsh deleted file mode 100644 index cb75af9..0000000 --- a/input/fsh/valueSets/BDConditionICD11VS.fsh +++ /dev/null @@ -1,6 +0,0 @@ -ValueSet: BDConditionICD11VS -Id: bd-condition-icd11-valueset -Title: "Bangladesh ICD-11 MMS ValueSet" -Description: "ValueSet that includes the ICD-11 MMS CodeSystem for Condition.code" -* ^url = "https://fhir.dghs.gov.bd/core/ValueSet/bd-condition-icd11-valueset" -* include codes from system http://id.who.int/icd/release/11/mms diff --git a/input/includes/menu.xml b/input/includes/menu.xml index c264dd9..c4d6c6d 100644 --- a/input/includes/menu.xml +++ b/input/includes/menu.xml @@ -19,6 +19,9 @@ <li> <a href="spec.html">Detailed Specification</a> </li> + <li> + <a href="icd11.html">ICD-11 Implementation</a> + </li> <li> <a href="fragments.html">Instance Fragments</a> </li> diff --git a/input/package-list.json b/input/package-list.json index 303ddcf..8dcbbd0 100644 --- a/input/package-list.json +++ b/input/package-list.json @@ -10,11 +10,19 @@ "path": "https://fhir.dghs.gov.bd/core/", "status": "ci-build", "current": true + }, + { + "version": "0.2.5", + "date": "2025-10-06", + "desc": "Minor bug fix release", + "path": "https://fhir.dghs.gov.bd/core/0.2.5/", + "status": "trial-use", + "sequence": "STU 1" }, { "version": "0.2.4", "date": "2025-10-06", - "desc": "Second draft release of the Bangladesh Core FHIR IG", + "desc": "Minor visual improvements", "path": "https://fhir.dghs.gov.bd/core/0.2.4/", "status": "trial-use", "sequence": "STU 1" @@ -22,7 +30,7 @@ { "version": "0.2.3", "date": "2025-10-06", - "desc": "Second draft release of the Bangladesh Core FHIR IG", + "desc": "Minor documentation updates", "path": "https://fhir.dghs.gov.bd/core/0.2.3/", "status": "trial-use", "sequence": "STU 1" @@ -30,7 +38,7 @@ { "version": "0.2.2", "date": "2025-10-06", - "desc": "Second draft release of the Bangladesh Core FHIR IG", + "desc": "Minor bug fix release", "path": "https://fhir.dghs.gov.bd/core/0.2.2/", "status": "trial-use", "sequence": "STU 1" diff --git a/input/pagecontent/icd11.md b/input/pagecontent/icd11.md new file mode 100644 index 0000000..0dc914c --- /dev/null +++ b/input/pagecontent/icd11.md @@ -0,0 +1,244 @@ +## ICD-11 Implementation + +### Overview + +The Bangladesh Core FHIR Implementation Guide uses ICD-11 Mortality and +Morbidity Statistics (MMS) as the mandatory coding system for clinical +conditions. This page documents the system URI, terminology infrastructure, +conformance requirements, and postcoordination conventions for implementers. + +--- + +### System URI + +All ICD-11 MMS codes SHALL use the WHO canonical system URI: +``` +http://id.who.int/icd/release/11/mms +``` + +The preferred code form is the short stem code (e.g. `1A00`, `NC72.Z`). +Linearization URIs are not used as code identifiers in this IG. + +--- + +### Terminology Infrastructure + +#### National OCL Terminology Server + +Runtime code validation and lookup are delegated to the national +OpenConceptLab (OCL) terminology server operated by DGHS/MoHFW: + +**Public FHIR R4 endpoint:** `https://tr.ocl.dghs.gov.bd` + +OCL hosts ICD-11 MMS version 2025-01 with 36,941 concepts across the +following concept classes: Diagnosis, Finding, Substance, Organism, +Device, Anatomy, and Misc. + +Vendors do not interact with OCL directly. All vendor submissions are +validated at the HIE boundary via the Bangladesh ICD-11 Cluster Validator +(see [Cluster Expressions](#cluster-expressions) below). + +#### Supported OCL Operations + +The following FHIR terminology operations are supported. The `system=` +parameter must be used — `url=` is not supported by OCL. + +**CodeSystem $validate-code** +``` +GET https://tr.ocl.dghs.gov.bd/api/fhir/CodeSystem/$validate-code + ?system=http://id.who.int/icd/release/11/mms&code={code} +``` + +**CodeSystem $lookup** +``` +GET https://tr.ocl.dghs.gov.bd/api/fhir/CodeSystem/$lookup + ?system=http://id.who.int/icd/release/11/mms&code={code} +``` + +**ValueSet $validate-code** +``` +GET https://tr.ocl.dghs.gov.bd/api/fhir/ValueSet/$validate-code + ?url=https://fhir.dghs.gov.bd/core/ValueSet/bd-condition-icd11-diagnosis-valueset + &system=http://id.who.int/icd/release/11/mms&code={code} +``` + +#### Unsupported OCL Operations + +`$expand` is not supported — this is a known limitation of the national +OCL instance. Build-time expansion is suppressed. Implementers SHALL NOT +depend on `$expand` for ICD-11 ValueSets in this IG. + +#### Local ICD-11 Docker Instance + +A local WHO ICD-11 Docker instance is maintained internally by DGHS at +`https://icd11.dghs.gov.bd` running release 2025-01. This instance is +internal only and is not exposed to vendors. It serves as the import +source for OCL and as the backend for the cluster validator. + +--- + +### Condition.code Binding and Class Restriction + +`Condition.code` is bound to the +[Bangladesh ICD-11 MMS Condition ValueSet](ValueSet-bd-condition-icd11-diagnosis-valueset.html) +at `preferred` strength. This ValueSet includes only Diagnosis (14,071) +and Finding (5,590) class concepts — 19,661 concepts total as of +version 2025-01. + +`Condition.code` SHALL contain at least one coding conforming to the +`coding[stem]` slice with `system = http://id.who.int/icd/release/11/mms`. +Vendors cannot omit ICD-11 by substituting a local code. + +The following concept classes SHALL NOT appear as standalone stem codes +in `Condition.code`: Substance, Organism, Device, Anatomy, Misc. + +This restriction exists because these classes represent entities that +are not themselves diagnoses or clinical findings — they are axes used +in postcoordination (e.g. a causative substance, an affected anatomy +site). Their correct use is as satellite codes within a cluster +expression, not as standalone condition codes. + +Class restriction is enforced at runtime via OCL ValueSet `$validate-code` +against the Bangladesh ICD-11 MMS Condition ValueSet. At the HAPI FHIR +layer, enforcement is via `RemoteTerminologyServiceValidationSupport` +configured to call OCL. HAPI FHIR deployment will be completed before +vendor onboarding. + +The `coding[stem]` slice is open (`#open`) — additional local codings +are permitted alongside the mandatory ICD-11 stem. + +--- + +### Cluster Expressions + +#### Background + +ICD-11 supports postcoordination — the combination of a stem code with +one or more satellite codes to precisely represent a clinical concept +that cannot be expressed by a stem code alone. A postcoordinated +expression is called a cluster expression. + +Cluster expressions are typically sourced from the WHO Electronic Coding +Tool (ECT) at the point of care. + +#### Syntax + +A cluster expression combines a stem code with satellite codes using +the `&` operator (combination) or `/` operator (specificity): +``` +NC72.Z&XK8G&XJ7ZH&XJ7YM +``` + +Where: +- `NC72.Z` — stem code: Fracture of femur, unspecified +- `XK8G` — satellite: laterality +- `XJ7ZH` — satellite: fracture subtype +- `XJ7YM` — satellite: fracture open or closed + +#### FHIR Representation + +The stem code is carried in `Coding.code`. The full cluster expression +is carried in the +[ICD-11 Cluster Expression extension](StructureDefinition-icd11-cluster-expression.html) +on the same `Coding` element: +```json +"code": { + "coding": [ + { + "system": "http://id.who.int/icd/release/11/mms", + "code": "NC72.Z", + "display": "Fracture of femur, unspecified", + "extension": [ + { + "url": "https://fhir.dghs.gov.bd/core/StructureDefinition/icd11-cluster-expression", + "valueString": "NC72.Z&XK8G&XJ7ZH&XJ7YM" + } + ] + } + ], + "text": "Fracture of femur, unspecified — left, transverse, closed" +} +``` + +The stem code in `Coding.code` SHALL match the leading stem code in the +cluster expression string. + +#### Stem-Only vs Cluster + +| Scenario | Representation | Validation | +|---|---|---| +| Single stem code | `Coding.code` only | OCL `$validate-code` | +| Postcoordinated expression | `Coding.code` + cluster extension | Cluster Validator | + +The cluster validator explicitly rejects stem-only expressions. Single +stem codes SHALL be represented in `Coding.code` only and validated via +OCL `$validate-code`. + +#### Satellite Code Class Restriction Exemption + +Satellite codes in a cluster expression are exempt from the +Diagnosis/Finding class restriction that applies to stem codes in +`Condition.code`. Substance, Anatomy, Organism, and other axis codes +are valid and expected as satellites. + +#### Bangladesh ICD-11 Cluster Validator + +All postcoordinated cluster expressions SHALL be validated against the +Bangladesh ICD-11 Cluster Validator prior to submission to the HIE: +``` +POST https://icd11.dghs.gov.bd/cluster/validate +Content-Type: application/json + +{"expression": "NC72.Z&XK8G&XJ7ZH&XJ7YM"} +``` + +Example response: +```json +{ + "valid": true, + "stem": { + "code": "NC72.Z", + "display": "Fracture of femur, unspecified", + "ocl_validated": true + }, + "satellites": [ + {"code": "XK8G", "axis": "laterality", "valid": true}, + {"code": "XJ7ZH", "axis": "fractureSubtype", "valid": true}, + {"code": "XJ7YM", "axis": "fractureOpenOrClosed", "valid": true} + ], + "errors": [] +} +``` + +The cluster validator is a mandatory HIE boundary gate. All vendor +submissions containing postcoordinated ICD-11 expressions pass through it. + +--- + +### Conformance Statements + +**ICD-11-CONF-01:** ICD-11 MMS codes SHALL use system URI +`http://id.who.int/icd/release/11/mms`. Stem code validation is available +via OCL at: +`https://tr.ocl.dghs.gov.bd/api/fhir/CodeSystem/$validate-code?system=http://id.who.int/icd/release/11/mms&code={code}` + +**ICD-11-CONF-02:** The `icd11-cluster-expression` extension SHALL only +be present when the expression contains at least one postcoordination +satellite code using `&` or `/` operators. Single stem codes SHALL be +represented in `Coding.code` only and validated via OCL `$validate-code`. + +**ICD-11-CONF-03:** Postcoordinated cluster expressions SHALL be validated +against the Bangladesh ICD-11 Cluster Validator at +`https://icd11.dghs.gov.bd/cluster/validate` prior to submission to the HIE. + +**ICD-11-CONF-04:** `Condition.code` SHALL contain at least one coding +conforming to the `coding[stem]` slice with +`system = http://id.who.int/icd/release/11/mms`. The stem code SHALL be +a member of the Bangladesh ICD-11 MMS Condition ValueSet, which includes +only Diagnosis and Finding class concepts. This restriction is enforced +at runtime via OCL ValueSet `$validate-code`. + +**ICD-11-CONF-05:** Substance, Organism, Device, Anatomy, and Misc class +ICD-11 concepts SHALL NOT appear as standalone stem codes in +`Condition.code`. This restriction does not apply to satellite codes +carried in the `icd11-cluster-expression` extension. \ No newline at end of file diff --git a/input/pagecontent/spec.md b/input/pagecontent/spec.md index 446a543..af7b55d 100644 --- a/input/pagecontent/spec.md +++ b/input/pagecontent/spec.md @@ -1,5 +1,135 @@ -### A Heading -You can also use markdown if that's your thing +## Bangladesh Core FHIR Implementation Guide — General Specification -And an icon: ![resource](icon-resource.png) +### Purpose and Scope +This Implementation Guide (IG) defines the national FHIR R4 core profiles, +value sets, code systems, extensions, and implementation rules for digital +health systems in Bangladesh. It is published by the Directorate General of +Health Services (DGHS), Ministry of Health and Family Welfare (MoHFW). + +This IG is a foundational component of the **Shareable Health Record (SHR)** +system — the national Health Information Exchange (HIE) and gateway for +producing a Personal Health Profile for every citizen of Bangladesh. + +This IG is aligned with and gives technical expression to: +- **Bangladesh Digital Health Strategy 2023–2027** +- **Bangladesh Digital Health Architecture Blueprint** + +The Patient profile strictly conforms to the **Citizen Core Data Structure +(CCDS)** defined by the Cabinet Division of the Government of Bangladesh. + +--- + +### Intended Audience + +This IG is addressed to all software systems exchanging health data with +the national SHR, including but not limited to: + +- Electronic Medical Record (EMR) systems +- Laboratory Information Systems (LIS) +- Picture Archiving and Communication Systems (PACS) +- Hospital Information Systems (HIS) + +This includes systems operated by public sector facilities, private +hospitals and clinics, autonomous bodies, and non-governmental +organisations (NGOs) operating within Bangladesh. + +--- + +### FHIR Version and Conventions + +This IG is built on **FHIR R4 (4.0.1)**. All profiles, extensions, value +sets, and code systems defined here conform to the FHIR R4 specification. + +Conformance language in this IG follows **RFC 2119**: SHALL, SHALL NOT, +SHOULD, SHOULD NOT, and MAY carry their standard normative meanings. + +--- + +### Design Principles + +**1. National terminology over international defaults** +Where international code systems are used (ICD-11, LOINC, SNOMED CT), +they are bound through national infrastructure. The national OpenConceptLab +(OCL) terminology server at `https://tr.ocl.dghs.gov.bd` is the single +public-facing terminology resolution point. Vendors never interact with +upstream terminology sources directly. + +**2. HIE boundary enforcement** +All vendor submissions pass through the national SHR HIE boundary. Mandatory +validation gates — including the Bangladesh ICD-11 Cluster Validator — are +applied at the HIE layer. Profile conformance is a necessary but not +sufficient condition for acceptance; HIE boundary rules apply additionally. + +**3. Open slicing for extensibility** +Where slices are defined on coding elements, slicing is open (`#open`). +Mandatory slices enforce the presence of nationally required codes; +additional local or proprietary codings are permitted alongside them. +This ensures national interoperability without preventing systems from +carrying additional coded data. + +**4. Citizen-centred identity** +The Patient profile conforms to the Citizen Core Data Structure (CCDS), +ensuring that patient identity in the SHR is anchored to the national +citizen identity infrastructure. + +**5. Must Support obligations** +Must Support (MS) in this IG means that conformant systems SHALL be capable +of populating the element if the data is held by the system, and SHALL be +capable of processing it when received. Specific sender and receiver +obligations are \[TODO: to be defined in a future revision\]. + +--- + +### Profiles + +The following national core profiles are defined in this IG: + +| Profile | Base Resource | Purpose | +|---|---|---| +| [BD Patient](StructureDefinition-bd-patient.html) | Patient | Citizen identity conforming to CCDS | +| [BD Condition](StructureDefinition-bd-condition.html) | Condition | Clinical conditions coded with ICD-11 MMS | +| [BD Observation](StructureDefinition-bd-observation.html) | Observation | Vital signs, laboratory results, clinical findings | +| [BD Encounter](StructureDefinition-bd-encounter.html) | Encounter | Clinical visits and episodes of care | +| [BD Medication](StructureDefinition-bd-medication.html) | Medication | Medication definitions | +| [BD MedicationRequest](StructureDefinition-bd-medicationrequest.html) | MedicationRequest | Prescriptions and medication orders | +| [BD Immunization](StructureDefinition-bd-immunization.html) | Immunization | Vaccination records | +| [BD Organization](StructureDefinition-bd-organization.html) | Organization | Health facilities and organisations | +| [BD Practitioner](StructureDefinition-bd-practitioner.html) | Practitioner | Healthcare providers | +| [BD Location](StructureDefinition-bd-location.html) | Location | Physical locations and administrative geography | + +--- + +### Terminology + +The following external code systems are used in this IG: + +| System | URI | Purpose | +|---|---|---| +| ICD-11 MMS | `http://id.who.int/icd/release/11/mms` | Condition coding | +| LOINC | `http://loinc.org` | Observation coding | +| UCUM | `http://unitsofmeasure.org` | Observation units | +| SNOMED CT | `http://snomed.info/sct` | Clinical terminology | + +Runtime terminology resolution is provided by the national OCL terminology +server. See the [ICD-11 Implementation](icd11.html) page for full details +of ICD-11 integration, postcoordination conventions, and conformance +requirements. + +--- + +### Known Gaps and Planned Work + +This IG is currently at version 0.2.5 with status `draft`. The following +are known gaps to be addressed in future revisions: + +- **Must Support semantics** — sender and receiver obligations not yet + formally defined +- **Capability Statements** — no CapabilityStatement resources defined yet +- **Search Parameters** — no defined search parameter requirements yet +- **Transaction Patterns** — no defined FHIR transaction or message patterns yet +- **HAPI FHIR deployment** — `RemoteTerminologyServiceValidationSupport` + configuration for OCL not yet deployed; this is a prerequisite for + runtime ICD-11 class restriction enforcement before vendor onboarding +- **Must Support definitions per profile** — individual profile pages do + not yet carry explicit MS obligation tables diff --git a/package-feed.xml b/package-feed.xml deleted file mode 100644 index 44d4572..0000000 --- a/package-feed.xml +++ /dev/null @@ -1,33 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<feed xmlns="http://www.w3.org/2005/Atom"> - <id>https://fhir.dghs.gov.bd/core/package-feed.xml</id> - <title>Bangladesh Core FHIR IG Package Feed - FHIR Package Feed for bd.fhir.core - - - 2025-10-02T00:00:00Z - - MIS, Directorate General of Health Services (DGHS), Bangladesh - https://dghs.gov.bd - - - - - - - - bd.fhir.core version 0.2.0 - - https://fhir.dghs.gov.bd/core/0.2.0/ - 2025-10-02T00:00:00Z - First draft release of Bangladesh Core FHIR Implementation Guide - - diff --git a/package-list.backup b/package-list.backup deleted file mode 100644 index fb2cc50..0000000 --- a/package-list.backup +++ /dev/null @@ -1,23 +0,0 @@ -{ - "package-id": "bd.fhir.core", - "title": "Bangladesh Core FHIR Implementation Guide", - "canonical": "https://fhir.dghs.gov.bd", - "introduction": "The Bangladesh Core FHIR IG defines national base profiles, value sets, and extensions for health data interoperability.", - "list": [ - { - "version": "current", - "desc": "Continuous Integration Build (latest development version)", - "path": "https://fhir.dghs.gov.bd/build", - "status": "ci-build", - "current": true - }, - { - "version": "v0.2.0", - "date": "2025-10-02", - "desc": "First draft release of the Bangladesh Core FHIR IG.", - "path": "https://fhir.dghs.gov.bd/v0.2.0", - "status": "trial-use", - "sequence": "STU 1" - } - ] -} diff --git a/package-list.json b/package-list.json index 303ddcf..8dcbbd0 100644 --- a/package-list.json +++ b/package-list.json @@ -10,11 +10,19 @@ "path": "https://fhir.dghs.gov.bd/core/", "status": "ci-build", "current": true + }, + { + "version": "0.2.5", + "date": "2025-10-06", + "desc": "Minor bug fix release", + "path": "https://fhir.dghs.gov.bd/core/0.2.5/", + "status": "trial-use", + "sequence": "STU 1" }, { "version": "0.2.4", "date": "2025-10-06", - "desc": "Second draft release of the Bangladesh Core FHIR IG", + "desc": "Minor visual improvements", "path": "https://fhir.dghs.gov.bd/core/0.2.4/", "status": "trial-use", "sequence": "STU 1" @@ -22,7 +30,7 @@ { "version": "0.2.3", "date": "2025-10-06", - "desc": "Second draft release of the Bangladesh Core FHIR IG", + "desc": "Minor documentation updates", "path": "https://fhir.dghs.gov.bd/core/0.2.3/", "status": "trial-use", "sequence": "STU 1" @@ -30,7 +38,7 @@ { "version": "0.2.2", "date": "2025-10-06", - "desc": "Second draft release of the Bangladesh Core FHIR IG", + "desc": "Minor bug fix release", "path": "https://fhir.dghs.gov.bd/core/0.2.2/", "status": "trial-use", "sequence": "STU 1" diff --git a/publication-request.backup b/publication-request.backup deleted file mode 100644 index 931e57c..0000000 --- a/publication-request.backup +++ /dev/null @@ -1,12 +0,0 @@ -{ - "package-id": "bd.fhir.core", - "title": "Bangladesh Core FHIR Implementation Guide", - "canonical": "https://fhir.dghs.gov.bd", - "version": "0.2.0", - "path": "https://fhir.dghs.gov.bd", - "status": "trial-use", - "sequence": "STU 1", - "mode": "milestone", - "desc": "First draft release of the Bangladesh Core FHIR IG.", - "first": true -} diff --git a/sushi-config.yaml b/sushi-config.yaml index 7d40c76..3f5d2a0 100644 --- a/sushi-config.yaml +++ b/sushi-config.yaml @@ -6,7 +6,7 @@ description: > This Implementation Guide defines the Bangladesh Core FHIR profiles, value sets, code systems, and implementation rules for national digital health systems. status: draft -version: 0.2.5 +version: 0.3.0 fhirVersion: 4.0.1 copyrightYear: 2025+ releaseLabel: CI Build