BFD-4648: Update BFD v3 to C4BB 2.2.0 (#3112)

Author: alex-dzeda

apps/bfd-model-idr/README.md

@@ -60,20 +60,24 @@ This will generate the StructureDefinition and CodeSystem resources necessary fo
 
 To reduce dependencies on tx.fhir.org as well as improve the speed of validation, we use matchbox to run a local FHIR server. Read more about matchbox at <https://ahdis.github.io/matchbox/>
 
-Note: Matchbox uses a significant amount of memory. Allocating at least 8GB of RAM is recommended, and more may be necessary in the future.
+Note: Matchbox uses a good bit of memory. Allocating at least 8GB of RAM is recommended. When new version dependencies are added, the heap allocated required should be re-evaluated. The compose setup is optimized to GC aggressively to reduce the impact. 
 
 To start matchbox, run
 
 ```sh
 docker compose up -d
 ```
 
-Note, it takes several minutes and requires a good bit of RAM. It'll be ready once it says that packages have been loaded and some obviously untrue amount of RAM (generally half of what it actually used) was used. Additionally, one can check the logs for "Finished engines during startup" or running a health check using
+Note, it takes several minutes and requires a good bit of RAM. Once the uploads from matchbox-setup are completed, matchbox should be ready to use. Additionally, matchbox has a health check available at:
 
 ```sh
 curl -X GET "http://localhost:8080/matchboxv3/actuator/health"
 ```
 
+### Referencing New/Updated Dependencies for Matchbox
+
+As new versions of IGs are released, they may have multiple nested dependencies. This takes up a significant amount of memory if loaded directly into Matchbox. To eliminate heap errors while still being able to accurately validate profiles and terminology, we download the FHIR Packages locally, untar them, and upload relevant resources directly to Matchbox. The list of resources + packages are in matchbox_profiles.txt. To add a new IG reference, follow the syntax in that file. Packages are only uploaded using docker compose up (by calling setup_matchbox.py), so restart the composition if adding more dependencies. 
+
 ### Create FHIR files with synthetic data
 
 Requires Matchbox to be active.

apps/bfd-model-idr/application.yaml

@@ -14,17 +14,32 @@ spring:
   jpa:
     properties:
       hibernate.dialect: org.hibernate.dialect.PostgreSQLDialect
+      hibernate.search.enabled: false
+      hibernate.cache.use_second_level_cache: false
+      hibernate.cache.use_query_cache: false
 matchbox:
   fhir:
     context:
       displayIssuesAreWarnings: false
       txServer: http://localhost:8080/matchboxv3/tx
       onlyOneEngine: true
-      igsPreloaded: hl7.fhir.us.carin-bb#2.1.0
+      fhirVersion: R4
+      suppressR5: true
+logging:
+  level:
+    ca.uhn.fhir: ERROR
+    ca.uhn.fhir.rest.server.ResourceBinding: ERROR
+    ch.ahdis.matchbox: DEBUG
 hapi:
   fhir:
-    implementationguides:
-      carin:
-        name: hl7.fhir.us.carin-bb
-        version: 2.1.0
+    fhir_version: R4
+    mdm_enabled: false
+    openapi_enabled: false
+    narrative_enabled: false
+    jpa:
+      subscription_matching_enabled: false
+      bulk_export_enabled: false
+      dao_scheduling_enabled: false
+      enforce_referential_integrity_on_delete: false
+      enforce_referential_integrity_on_write: false
 

apps/bfd-model-idr/augment_sample_resources.py

@@ -51,6 +51,8 @@
     "CLM_NGACO_CPTATN_SW": "CLM_NGACO_CPTATN_SW",
     "CLM_ACO_CARE_MGMT_HCBS_SW": "CLM_ACO_CARE_MGMT_HCBS_SW",
     "CLM_PD_STUS_CD": "CLM_PD_STUS_CD",
+    "CLM_NRLN_RIC_CD": "CLM_NRLN_RIC_CD",
+    "CLM_RIC_CD": "CLM_RIC_CD",
     "GEO_BLG_SSA_STATE_CD": "GEO_BLG_SSA_STATE_CD",
 }
 
@@ -411,7 +413,7 @@ def next_row_num(supporting_info):
 
 filename = "out/temporary-sample.json"
 
-cur_sample_data["lastUpdated"] = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+cur_sample_data["lastUpdated"] = "2026-01-01T03:02:28.000000Z"
 
 with Path(filename).open("w") as f:
     json.dump(cur_sample_data, f, indent=4)

apps/bfd-model-idr/compile_resources.py

@@ -238,7 +238,7 @@ def main():
     print("Executing Transform")
     execute_cmd = f"java -jar validator_cli.jar {input_file} -output {args.output} -transform \
         {args.resource} -version 4.0.1 -ig {compiled_map_path} \
-            -ig hl7.fhir.us.carin-bb#2.1.0 {map_imports} {sushi_resources} -tx {MATCHBOX_SERVER}/tx"
+            -ig hl7.fhir.us.carin-bb#2.2.0 {map_imports} {sushi_resources} -tx {MATCHBOX_SERVER}/tx"
     stdout, stderr = run_command(execute_cmd, cwd=script_dir)
 
     print("Execution output:")

apps/bfd-model-idr/dictionary-support-files/ExplanationOfBenefit.yaml

@@ -1211,7 +1211,7 @@
     - CCLFA.CLM_1_REV_CNTR_ANSI_RSN_CD
   sourceView: V2_MDCR_CLM_ANSI_SGNTR
   sourceColumn: CLM_1_REV_CNTR_ANSI_RSN_CD
-  fhirPath: ExplanationOfBenefit.item.adjudication.reason.coding.where(system='https://bluebutton.cms.gov/fhir/CodeSystem/ANSI-RSN-CODE').code
+  fhirPath: ExplanationOfBenefit.item.adjudication.reason.coding.where(system='https://bluebutton.cms.gov/fhir/CodeSystem/ANSI-RSN-CD').code
   notes: ANSI reason and group codes are unordered.
 - inputPath: LineItemComponent.CLM_1_REV_CNTR_ANSI_GRP_CD
   appliesTo:
@@ -1228,7 +1228,7 @@
     - CCLFA.CLM_1_REV_CNTR_ANSI_GRP_CD
   sourceView: V2_MDCR_CLM_ANSI_SGNTR
   sourceColumn: CLM_1_REV_CNTR_ANSI_GRP_CD
-  fhirPath: ExplanationOfBenefit.item.adjudication.reason.coding.where(system='https://bluebutton.cms.gov/fhir/CodeSystem/ANSI-GRP-CODE').code
+  fhirPath: ExplanationOfBenefit.item.adjudication.reason.coding.where(system='https://bluebutton.cms.gov/fhir/CodeSystem/ANSI-GRP-CD').code
   notes: ANSI reason and group codes are unordered. 
 - inputPath: LineItemComponent.CLM_2_REV_CNTR_ANSI_RSN_CD
   appliesTo:
@@ -1243,7 +1243,7 @@
     - REV_CNTR_2ND_ANSI_CD
   sourceView: V2_MDCR_CLM_ANSI_SGNTR
   sourceColumn: CLM_2_REV_CNTR_ANSI_RSN_CD
-  fhirPath: ExplanationOfBenefit.item.adjudication.reason.coding.where(system='https://bluebutton.cms.gov/fhir/CodeSystem/ANSI-RSN-CODE').code
+  fhirPath: ExplanationOfBenefit.item.adjudication.reason.coding.where(system='https://bluebutton.cms.gov/fhir/CodeSystem/ANSI-RSN-CD').code
   notes: ANSI reason and group codes are unordered.
 - inputPath: LineItemComponent.CLM_2_REV_CNTR_ANSI_GRP_CD
   appliesTo:
@@ -1258,7 +1258,7 @@
     - REV_CNTR_2ND_ANSI_CD
   sourceView: V2_MDCR_CLM_ANSI_SGNTR
   sourceColumn: CLM_2_REV_CNTR_ANSI_GRP_CD
-  fhirPath: ExplanationOfBenefit.item.adjudication.reason.coding.where(system='https://bluebutton.cms.gov/fhir/CodeSystem/ANSI-GRP-CODE').code
+  fhirPath: ExplanationOfBenefit.item.adjudication.reason.coding.where(system='https://bluebutton.cms.gov/fhir/CodeSystem/ANSI-GRP-CD').code
   notes: ANSI reason and group codes are unordered. 
 - inputPath: LineItemComponent.CLM_3_REV_CNTR_ANSI_RSN_CD
   appliesTo:
@@ -1273,7 +1273,7 @@
     - REV_CNTR_3RD_ANSI_CD
   sourceView: V2_MDCR_CLM_ANSI_SGNTR
   sourceColumn: CLM_3_REV_CNTR_ANSI_RSN_CD
-  fhirPath: ExplanationOfBenefit.item.adjudication.reason.coding.where(system='https://bluebutton.cms.gov/fhir/CodeSystem/ANSI-RSN-CODE').code
+  fhirPath: ExplanationOfBenefit.item.adjudication.reason.coding.where(system='https://bluebutton.cms.gov/fhir/CodeSystem/ANSI-RSN-CD').code
   notes: ANSI reason and group codes are unordered.
 - inputPath: LineItemComponent.CLM_3_REV_CNTR_ANSI_GRP_CD
   appliesTo:
@@ -1288,7 +1288,7 @@
     - REV_CNTR_3RD_ANSI_CD
   sourceView: V2_MDCR_CLM_ANSI_SGNTR
   sourceColumn: CLM_3_REV_CNTR_ANSI_GRP_CD
-  fhirPath: ExplanationOfBenefit.item.adjudication.reason.coding.where(system='https://bluebutton.cms.gov/fhir/CodeSystem/ANSI-GRP-CODE').code
+  fhirPath: ExplanationOfBenefit.item.adjudication.reason.coding.where(system='https://bluebutton.cms.gov/fhir/CodeSystem/ANSI-GRP-CD').code
   notes: ANSI reason and group codes are unordered. 
 - inputPath: LineItemComponent.CLM_4_REV_CNTR_ANSI_RSN_CD
   appliesTo:
@@ -1303,7 +1303,7 @@
     - REV_CNTR_4TH_ANSI_CD
   sourceView: V2_MDCR_CLM_ANSI_SGNTR
   sourceColumn: CLM_4_REV_CNTR_ANSI_RSN_CD
-  fhirPath: ExplanationOfBenefit.item.adjudication.reason.coding.where(system='https://bluebutton.cms.gov/fhir/CodeSystem/ANSI-RSN-CODE').code
+  fhirPath: ExplanationOfBenefit.item.adjudication.reason.coding.where(system='https://bluebutton.cms.gov/fhir/CodeSystem/ANSI-RSN-CD').code
   notes: ANSI reason and group codes are unordered.
 - inputPath: LineItemComponent.CLM_4_REV_CNTR_ANSI_GRP_CD
   appliesTo:
@@ -1318,7 +1318,7 @@
     - REV_CNTR_4TH_ANSI_CD
   sourceView: V2_MDCR_CLM_ANSI_SGNTR
   sourceColumn: CLM_4_REV_CNTR_ANSI_GRP_CD
-  fhirPath: ExplanationOfBenefit.item.adjudication.reason.coding.where(system='https://bluebutton.cms.gov/fhir/CodeSystem/ANSI-GRP-CODE').code
+  fhirPath: ExplanationOfBenefit.item.adjudication.reason.coding.where(system='https://bluebutton.cms.gov/fhir/CodeSystem/ANSI-GRP-CD').code
   notes: ANSI reason and group codes are unordered. 
 - inputPath: LineItemComponent.CLM_LINE_NCVRD_CHRG_AMT
   appliesTo:

apps/bfd-model-idr/docker-compose.yml

@@ -1,15 +1,32 @@
 services:
   matchbox:
-    image: europe-west6-docker.pkg.dev/ahdis-ch/ahdis/matchbox:v4.0.18
+    image: europe-west6-docker.pkg.dev/ahdis-ch/ahdis/matchbox:v4.1.5
     container_name: matchbox
     restart: on-failure
     ports:
       - "8080:8080"
     depends_on:
       - matchbox-db
-    entrypoint: ["java", "-Xms2G", "-Xmx10G", "-Dfhir.settings.path=/config/fhir-settings.json", "-Dspring.config.additional-location=optional:file:/config/application.yaml,optional:file:application.yaml", "-jar", "/matchbox.jar"]
+    entrypoint: ["java", "-Xms512m", "-Xmx6G", "-XX:+UseZGC", "-XX:ZUncommitDelay=30", "-XX:MaxMetaspaceSize=512m", "-Dfhir.settings.path=/config/fhir-settings.json", "-Dspring.config.additional-location=optional:file:/config/application.yaml", "-jar", "/matchbox.jar"]
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8080/matchboxv3/fhir/metadata"]
+      interval: 5s
+      timeout: 5s
+      retries: 30
     volumes:
       - ./:/config/
+  matchbox-setup:
+    image: ghcr.io/astral-sh/uv:python3.14-alpine
+    volumes:
+      - ./:/app
+    working_dir: /app
+    depends_on:
+      matchbox:
+        condition: service_healthy
+    environment:
+      - UV_PYTHON=3.14.3
+      - UV_PROJECT_ENVIRONMENT=/tmp/.venv
+    command: uv run setup_matchbox.py --url http://matchbox:8080/matchboxv3/fhir
   matchbox-db:
     image: postgres:17.7
     container_name: matchbox-db

apps/bfd-model-idr/fhir-settings.json

@@ -0,0 +1,4 @@
+{
+  "fhirVersion": "R4",
+  "suppressR5": true
+}

apps/bfd-model-idr/maps/Coverage-Base.map

@@ -17,8 +17,8 @@ group createCoverageBase(source src: CoverageBase, target tgt: BFDCoverage){
     } "Add ID key";
     src -> tgt.meta = create('Meta') as tgtMeta then{
         src.lastUpdated as lastUpdated -> tgtMeta.lastUpdated = lastUpdated "Set lastUpdated";
-        src -> tgtMeta.profile = "http://hl7.org/fhir/us/carin-bb/StructureDefinition/C4BB-Coverage|2.1.0" "Set C4BB profile";
-        src -> tgtMeta.profile = "http://hl7.org/fhir/us/core/StructureDefinition/us-core-coverage|6.1.0" "Set US Core profile";
+        src -> tgtMeta.profile = "http://hl7.org/fhir/us/carin-bb/StructureDefinition/C4BB-Coverage|2.2.0" "Set C4BB profile";
+        src -> tgtMeta.profile = "http://hl7.org/fhir/us/core/StructureDefinition/us-core-coverage|7.0.0" "Set US Core profile";
     } "add metadata";
     src.XREF_EFCTV_BENE_SK as beneSk -> tgt.beneficiary = create('Reference') as tgtReference,
         tgtReference.reference = append("Patient/",beneSk) "Set bene_sk";
@@ -174,7 +174,10 @@ group createPartDCoverage(source src: CoverageBase, target tgt: BFDCoverage){
 
     src.BENE_ENRLMT_EMPLR_SBSDY_SW as switch -> tgt.extension = create('Extension') as tgtExtension then{
         src -> tgtExtension.url = "https://bluebutton.cms.gov/fhir/StructureDefinition/BENE-ENRLMT-EMPLR-SBSDY-SW" "Add url";
-        src -> tgtExtension.value = switch "Add value";
+        src -> tgtExtension.value = create('Coding') as tgtCoding then{
+            src -> tgtCoding.system = "https://bluebutton.cms.gov/fhir/CodeSystem/BENE-ENRLMT-EMPLR-SBSDY-SW" "add system";
+            src -> tgtCoding.code = switch "Add code";
+        } "Add coding";
     } "Add RDS switch ";
 
     //Coverage Type Code Extension
@@ -492,7 +495,7 @@ group AddPartBCoverageElements(source src: CoverageBase, target tgt: BFDCoverage
 
 group SetOrganizationEntryCMS(source src : CoverageBase, target tgt : Organization) {
     src -> tgt.meta = create('Meta') as tgtMeta then{
-        src -> tgtMeta.profile = "http://hl7.org/fhir/us/carin-bb/StructureDefinition/C4BB-Organization|2.1.0" "set profile";
+        src -> tgtMeta.profile = "http://hl7.org/fhir/us/carin-bb/StructureDefinition/C4BB-Organization|2.2.0" "set profile";
     } "add metadata";
 
     src -> tgt.id = "cms-org" "set org id";
@@ -519,7 +522,7 @@ group SetOrganizationEntryCMS(source src : CoverageBase, target tgt : Organizati
 //Source this information from the respective tables
 group SetOrganizationEntryPartCD(source src : CoverageBase, target tgt : Organization) {
     src -> tgt.meta = create('Meta') as tgtMeta then{
-        src -> tgtMeta.profile = "http://hl7.org/fhir/us/carin-bb/StructureDefinition/C4BB-Organization|2.1.0" "set profile";
+        src -> tgtMeta.profile = "http://hl7.org/fhir/us/carin-bb/StructureDefinition/C4BB-Organization|2.2.0" "set profile";
     } "add metadata";
 
     src -> tgt.id = "insurer-org" "set org id";

apps/bfd-model-idr/maps/ExplanationOfBenefit-Base.map

@@ -566,8 +566,8 @@ group addProcedures(source src: ProcedureComponent, target tgt: BackboneElement)
 group createInsurerOrgPartAB(source src: ExplanationOfBenefitBase, target tgtOrg: Organization){
   src -> tgtOrg.id = "insurer-org" "Set org id";
   src -> tgtOrg.meta = create('Meta') as tgtMeta then {
-    src -> tgtMeta.profile = "http://hl7.org/fhir/us/carin-bb/StructureDefinition/C4BB-Organization|2.1.0" "Set org profile";
-    src -> tgtMeta.profile = "http://hl7.org/fhir/us/core/StructureDefinition/us-core-organization|6.1.0" "Set org profile";
+    src -> tgtMeta.profile = "http://hl7.org/fhir/us/carin-bb/StructureDefinition/C4BB-Organization|2.2.0" "Set org profile";
+    src -> tgtMeta.profile = "http://hl7.org/fhir/us/core/StructureDefinition/us-core-organization|7.0.0" "Set org profile";
   } "Set organization metadata";
   src -> tgtOrg.active = "true" "set org status";
   src -> tgtOrg.name = "Centers for Medicare & Medicaid Services" "set org name";
@@ -594,8 +594,8 @@ group createOrg(source src: Provider, target tgt: Organization){
 
   //when PRVDR_SK is missing (eg NPI) these won't conform, so don't add the profile. 
   src.PRVDR_SK as sk -> tgt.meta = create('Meta') as tgtMeta then {
-          src -> tgtMeta.profile = "http://hl7.org/fhir/us/carin-bb/StructureDefinition/C4BB-Organization|2.1.0" "Set org profile";
-          src -> tgtMeta.profile = "http://hl7.org/fhir/us/core/StructureDefinition/us-core-organization|6.1.0" "Set org profile";
+          src -> tgtMeta.profile = "http://hl7.org/fhir/us/carin-bb/StructureDefinition/C4BB-Organization|2.2.0" "Set org profile";
+          src -> tgtMeta.profile = "http://hl7.org/fhir/us/core/StructureDefinition/us-core-organization|7.0.0" "Set org profile";
   } "Set Org metadata";
   src -> tgt.active = "true" "set org status";
 
@@ -631,8 +631,8 @@ group createPractitioner(source src: Provider, target tgt: Practitioner){
   } "Add qualifier code and id num";
 
   src -> tgt.meta = create('Meta') as tgtMeta then {
-          src -> tgtMeta.profile = "http://hl7.org/fhir/us/carin-bb/StructureDefinition/C4BB-Practitioner|2.1.0" "Set profile";
-          src -> tgtMeta.profile = "http://hl7.org/fhir/us/core/StructureDefinition/us-core-practitioner|6.1.0" "Set profile";
+          src -> tgtMeta.profile = "http://hl7.org/fhir/us/carin-bb/StructureDefinition/C4BB-Practitioner|2.2.0" "Set profile";
+          src -> tgtMeta.profile = "http://hl7.org/fhir/us/core/StructureDefinition/us-core-practitioner|7.0.0" "Set profile";
   } "Set practitioner metadata";
 
   src -> tgt.identifier = create('Identifier') as tgtId then {