Prepare 0.3.0: ICD-11 MMS integration

2026-03-08 14:40:19 +06:00
parent 4813f63da5
commit 49b3d72cb2
17 changed files with 662 additions and 132 deletions
--- a/input/bd.fhir.core.xml
+++ b/input/bd.fhir.core.xml
@@ -13,7 +13,7 @@
  </extension>-->
  <url value="https://fhir.dghs.gov.bd/core/ImplementationGuide/bd.fhir.core"/>
  <!-- This version will propagate to all artifacts unless the "propagate-version" extension is overridden -->
-  <version value="0.2.5"/>
+  <version value="0.3.0"/>
  <name value="BangladeshCoreFHIRIG"/>
  <title value="Bangladesh Core FHIR Implementation Guide"/>
  <status value="active"/>
--- a/input/fsh/BDConditionProfile.fsh
+++ b/input/fsh/BDConditionProfile.fsh
@@ -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)
--- a/input/fsh/extensions/icd11ClusterExpression.fsh
+++ 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.
+"""
--- a/input/fsh/immunization.json
+++ b/input/fsh/immunization.json
@@ -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
-      }
-    ]
-  }
-}
--- a/input/fsh/namingSystems/ICD11MMSNamingSystem.fsh
+++ 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."
--- a/input/fsh/profile/BDConditionProfile.fsh
+++ 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
--- a/input/fsh/valueSets/BDConditionICD11DiagnosisVS.fsh
+++ 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
--- a/input/fsh/valueSets/BDConditionICD11VS.fsh
+++ b/input/fsh/valueSets/BDConditionICD11VS.fsh
@@ -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
--- 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>
--- 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"
--- a/input/pagecontent/icd11.md
+++ 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.
--- 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
--- a/package-feed.xml
+++ b/package-feed.xml
@@ -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</title>
-  <subtitle>FHIR Package Feed for bd.fhir.core</subtitle>
-  <link rel="self" href="https://fhir.dghs.gov.bd/core/package-feed.xml"/>
-  <link rel="alternate" href="https://fhir.dghs.gov.bd/core/"/>
-  <updated>2025-10-02T00:00:00Z</updated>
-  <author>
-    <name>MIS, Directorate General of Health Services (DGHS), Bangladesh</name>
-    <uri>https://dghs.gov.bd</uri>
-  </author>
-  
-  <!-- Entries will be automatically added by the CI/CD pipeline -->
-  <!-- Example entry structure (will be generated): -->
-  <!--
-  <entry>
-    <title>bd.fhir.core version 0.2.0</title>
-    <link rel="alternate" href="https://fhir.dghs.gov.bd/core/0.2.0/"/>
-    <id>https://fhir.dghs.gov.bd/core/0.2.0/</id>
-    <updated>2025-10-02T00:00:00Z</updated>
-    <summary>Release 0.2.0 of Bangladesh Core FHIR Implementation Guide</summary>
-  </entry>
-  -->
-  
-  <entry>
-    <title>bd.fhir.core version 0.2.0</title>
-    <link rel="alternate" href="https://fhir.dghs.gov.bd/core/0.2.0/"/>
-    <id>https://fhir.dghs.gov.bd/core/0.2.0/</id>
-    <updated>2025-10-02T00:00:00Z</updated>
-    <summary>First draft release of Bangladesh Core FHIR Implementation Guide</summary>
-  </entry>
-</feed>
--- a/package-list.backup
+++ b/package-list.backup
@@ -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"
-    }
-  ]
-}
--- 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"
--- a/publication-request.backup
+++ b/publication-request.backup
@@ -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
-}
--- 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