CMS-0057-F Compliance: Installing and Validating IGs

This guide provides step-by-step instructions for installing and configuring a set of IGs commonly used for CMS-0057-F compliance. Please note that this guide targets FHIR R4. The module types (PERSISTENCE_R4) and all IGs listed are R4-based.

• R4B requires no changes. R4B uses the same PERSISTENCE_R4 module type in Smile CDR.
• For R5, replace PERSISTENCE_R4 with PERSISTENCE_R5 for both repositories. Note that ENDPOINT_PACKAGE_REGISTRY does not currently support R5. The CMS-0057-F compliance IGs listed in this guide are all R4-based, and R5 equivalents are not yet established for these IGs.

Contents

• Step 1. Set up the environment
• Step 2. Install external CodeSystems
  • Option A: Remote terminology server
  • Option B: Manual upload
• Step 3. Install terminology and validation resources
  • 3a. Install required IGs
  • 3b. Troubleshoot ValueSet expansion failures
• [Optional] Step 4. Load example non-conformance resources
• Step 5. Verify terminology operations and profile validation
  • 5a. Verify ValueSet expansion ($expand)
  • 5b. Verify code validation ($validate-code)
  • 5c. Verify code lookup ($lookup)
  • 5d. Validate resources against profiles ($validate)
• Step 6. Install other conformance resources
  • 6a. Install SearchParameters
  • 6b. Verify search

Step 1. Set up the environment

For larger deployments, separating conformance resources (StructureDefinitions, ValueSets, CodeSystems) from clinical data (Patient, ExplanationOfBenefit, Coverage) into two repositories allows each to be scaled and maintained independently. This guide uses that two-repository layout, with a Conformance Repository for conformance resources and a Content Repository for operational data, but a single repository can serve both roles. If you are using a single repository, all {CONFORMANCE_*} and {CONTENT_*} placeholders resolve to the same endpoints.

The user performing these steps needs the following permissions: PACKAGE_REGISTRY_WRITE (Steps 3, 4, and 6a), FHIR_UPLOAD_EXTERNAL_TERMINOLOGY (Steps 2–3), FHIR_MANUAL_VALIDATION (Step 5d), and ROLE_FHIR_TERMINOLOGY_READ (Steps 5a–5c). Alternatively, ROLE_SUPERUSER grants all of these.

Set up the modules below via the Web Admin Console or Node Configuration Properties File. See FHIR Storage (Relational) Module, FHIR Endpoint Module, and Package Registry Endpoint Module for details.

# ===== Conformance Repository - conformance resources (StructureDefinitions, ValueSets, CodeSystems, ConceptMaps, etc.) =====
module.conformance_persistence.type=PERSISTENCE_R4
module.conformance_persistence.config.search_parameter_seeding.support_default_search_parameters=true
module.conformance_persistence.config.scheduled_tasks.pre_expand_valuesets.enabled=true

# {CONFORMANCE_FHIR}
module.conformance_fhir_endpoint.type=ENDPOINT_FHIR_REST
module.conformance_fhir_endpoint.requires.PERSISTENCE_ALL=conformance_persistence
module.conformance_fhir_endpoint.config.base_url.fixed=https://cdr.acme.com:8000

# {CONFORMANCE_PKG_REGISTRY}
module.conformance_package_registry.type=ENDPOINT_PACKAGE_REGISTRY
module.conformance_package_registry.requires.PACKAGE_CACHE=conformance_persistence
module.conformance_package_registry.config.base_url.fixed=https://cdr.acme.com:8002

# ===== Content Repository - operational data + SearchParameters (Patient, ExplanationOfBenefit, Coverage, etc.) =====
module.content_persistence.type=PERSISTENCE_R4
module.content_persistence.config.dao_config.mark_resources_for_reindexing_after_sp_change=true
# [Optional] Required for Step 4 - allows the installer to auto-create stub targets for unresolved references.
module.content_persistence.config.dao_config.auto_create_placeholder_reference_targets.enabled=true

# {CONTENT_FHIR}
module.content_fhir_endpoint.type=ENDPOINT_FHIR_REST
module.content_fhir_endpoint.requires.PERSISTENCE_ALL=content_persistence
module.content_fhir_endpoint.config.base_url.fixed=https://cdr.acme.com:8010

# {CONTENT_PKG_REGISTRY}
module.content_package_registry.type=ENDPOINT_PACKAGE_REGISTRY
module.content_package_registry.requires.PACKAGE_CACHE=content_persistence
module.content_package_registry.config.base_url.fixed=https://cdr.acme.com:8012

Settings above can be updated (e.g. reverted back to original) once the setup is complete.

Step 2. Install external CodeSystems

The IGs you will install in Step 3 reference large external terminologies (e.g. ICD-10-CM, SNOMED CT, CPT) that are not bundled in the IG packages. There are two ways to resolve them:

• With Option A (Remote terminology server), Smile CDR forwards terminology operations to an external server. No downloads or format conversion required; $validate-code, $lookup, and on-demand $expand are handled by the remote server.
• With Option B (Manual upload), each CodeSystem is downloaded and uploaded into the local repository. Required for ValueSet pre-expansion with hierarchy filters (is-a, descendent-of), or when a remote terminology server is not available. Since a remote server can't cover pre-expansion with hierarchy filters, most deployments end up using both, with a remote server for some CodeSystems and manual upload for others.

Configure the Remote Terminology Service on the conformance_persistence module. When enabled, $validate-code, $lookup, and $expand requests for external CodeSystems are forwarded to the remote server automatically.

Limitation: The background pre-expansion job runs locally and cannot delegate to a remote server. ValueSets with hierarchy filters (is-a, descendent-of) on external CodeSystems will still fail to pre-expand unless those CodeSystems are also uploaded locally (Option B). If pre-expanded ValueSets are not required for your use case, the remote server alone is sufficient for validation and lookup.

Upload each CodeSystem (see Uploading CodeSystems). CodeSystems with a native Upload Format in the table above (XML, RF2 ZIP, LOINC ZIP) can be uploaded using their standard distribution files. CodeSystems listed as CSV must first be converted to a Vocabulary Input File Format. See How Uploaded Terminology Interacts with IG Packages for details on how uploaded terminology interacts with the content=not-present placeholder CodeSystems created during IG installation.

After each upload, verify the CodeSystem was loaded correctly using $lookup:

GET {CONFORMANCE_FHIR}/CodeSystem/$lookup?system=http://hl7.org/fhir/sid/icd-10-cm&code=I27.2

Expected result: Parameters with the code's display value (e.g. "Other secondary pulmonary hypertension").

Not every CodeSystem above may be needed for your use case, and conversely, some ValueSets may still fail to pre-expand once the IGs are installed if they reference a CodeSystem not covered here. See Step 3 for troubleshooting those failures and re-expanding.

Step 3. Install terminology and validation resources

Install the required IGs on the conformance repository, then confirm that all ValueSets pre-expanded successfully and troubleshoot any that didn't.

See NPM Packages and Implementation Guides for background on package installation.

The following IGs are commonly required for CMS-0057-F compliance (in package_name#package_version format):

• hl7.fhir.us.carin-bb#2.1.0
• hl7.fhir.us.davinci-pdex#2.1.0
• hl7.fhir.us.davinci-pdex-plan-net#1.2.0
• hl7.fhir.us.davinci-drug-formulary#2.1.0

For each package, invoke the install operation via PUT {CONFORMANCE_PKG_REGISTRY}/write/install/by-spec:

{
  "name": "hl7.fhir.us.carin-bb",
  "version": "2.1.0",
  "installMode": "INSTALL_ONLY",
  "installResourceTypes": ["NamingSystem", "CodeSystem", "ValueSet", "StructureDefinition", "ConceptMap"],
  "fetchDependencies": true
}

Key parameters to note:

• installResourceTypes excludes SearchParameter from this installation. SearchParameters will be installed separately in Step 6a on the content repository, where they are needed for search indexing. Depending on your use case, you may need to add other resource types (e.g. OperationDefinition, Questionnaire, Measure, Library). See Customizing Installed Resource Types for common candidates and how this parameter interacts with defaults.
• Setting fetchDependencies to true automatically downloads and installs all transitive dependencies. Alternatively, you can install all dependency packages explicitly in bottom-up order (e.g. hl7.fhir.r4.core, then hl7.fhir.us.core, then the main IGs) with fetchDependencies set to false. This gives full control over which dependency versions are installed, but requires knowing the full dependency tree in advance.
• [Optional] For large IGs with many dependencies, consider using asynchronous installation with the Prefer: respond-async header to avoid HTTP timeouts.

If the install operation fails, see Troubleshooting Package Installation for common issues including broken dependencies, network failures, FHIR version mismatches, and resource version conflicts.

After installation, the pre-expansion job will attempt to expand all installed ValueSets. Some may still fail — most commonly because they reference an external CodeSystem that wasn't uploaded in Step 2, or one outside that table entirely. Use Checking Expansion Status to see which ValueSets failed, then Troubleshooting Expansion Failures to diagnose why — that page and Re-expanding ValueSets after uploading external CodeSystems walk through uploading the missing CodeSystem and re-expanding as a pair.

If you are using Option A (remote terminology server) exclusively and pre-expanded ValueSets are not required for your use case, you can skip to Step 4. Otherwise, upload any missing CodeSystem following the same procedure described in Step 2, then re-expand the affected ValueSets.

As a quick check, verify that a previously failing ValueSet now expands:

GET {CONFORMANCE_FHIR}/ValueSet/$expand?url=http://hl7.org/fhir/us/carin-bb/ValueSet/C4BBEOBInstitutionalClaimSubType

Expected result: a ValueSet with a populated expansion. If it still fails, re-check the CodeSystem upload with $lookup as described in Step 2. Step 5 covers broader spot-checking of terminology operations across all installed IGs.

[Optional] Step 4. Load example (non-conformance) resources

Load IG-published example resources into the content repository to have ready-made data for profile validation in Step 5d and search verification in Step 6b. Skip this step if you will supply your own test data.

Prerequisite: auto_create_placeholder_reference_targets must be enabled (Step 1), as example resources reference each other across types. See References between instance resources for details.

For each package, install using PUT {CONTENT_PKG_REGISTRY}/write/install/by-spec:

{
  "name": "hl7.fhir.us.carin-bb",
  "version": "2.1.0",
  "installMode": "INSTALL_ONLY",
  "installResourceTypes": ["Patient", "Coverage", "ExplanationOfBenefit", "Organization",
                            "Practitioner", "PractitionerRole", "InsurancePlan", "Provenance"],
  "additionalResourceFolders": ["example"],
  "fetchDependencies": false
}

installResourceTypes lists the instance resource types present in the example folder. fetchDependencies is false because dependencies were already installed in Step 3.

Repeat for each of the four packages listed in Step 3.

Step 5. Verify terminology operations and profile validation

Verify that terminology operations and profile validation work correctly against the conformance repository. See Validation and Conformance Data for background.

GET {CONFORMANCE_FHIR}/ValueSet/$expand?url=http://hl7.org/fhir/us/carin-bb/ValueSet/C4BBClaimCareTeamRole

GET {CONFORMANCE_FHIR}/ValueSet/$expand?url=http://hl7.org/fhir/us/carin-bb/ValueSet/C4BBSupportingInfoType

GET {CONFORMANCE_FHIR}/ValueSet/$validate-code?url=http://hl7.org/fhir/us/carin-bb/ValueSet/C4BBClaimCareTeamRole&code=referring&system=http://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBClaimCareTeamRole

GET {CONFORMANCE_FHIR}/ValueSet/$validate-code?url=http://hl7.org/fhir/us/carin-bb/ValueSet/C4BBClaimCareTeamRole&code=nonexistent&system=http://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBClaimCareTeamRole

If you uploaded CodeSystems locally (Option B): a result = true on a valid code alone does not confirm local content is being consulted. For content=not-present CodeSystems with no local concepts, the server falls through to the next validator in the chain rather than returning "not found" (see Debugging missing content=not-present CodeSystems). Test with a known invalid code to confirm local content is authoritative:

GET {CONFORMANCE_FHIR}/ValueSet/$validate-code?url=http://hl7.org/fhir/us/carin-bb/ValueSet/C4BBDiagnosisType&code=INVALID-CODE&system=http://hl7.org/fhir/sid/icd-10-cm

Expected result: Parameters with result = false. Use $lookup (Step 5c) as an additional confirmation. A CodeSystem with local concepts will return a display value; one without will not.

GET {CONFORMANCE_FHIR}/CodeSystem/$lookup?system=http://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBSupportingInfoType&code=clmrecvddate

To do this you need example resources to validate against. If you completed Step 4, retrieve an example from the content repository and POST it directly. Otherwise, download the examples from the IG specification websites:

• CARIN BB 2.1.0, e.g. EOBProfessional1, Coverage1, Patient1
• Da Vinci PDex 2.1.0, e.g. MemberMatchExample
• Da Vinci Plan Net 1.2.0, e.g. AcmeOfCTStdNet, PharmChainAOrg
• Da Vinci Drug Formulary 2.1.0, e.g. FormularyD1002, FormularyItem-D1002-1000091

For a positive test, POST an example resource as the request body to $validate (e.g. EOBProfessional1 from CARIN BB):

POST {CONFORMANCE_FHIR}/ExplanationOfBenefit/$validate
Content-Type: application/fhir+json

<resource body>

Expected result: OperationOutcome with no error-severity issues (warnings are acceptable).

For a negative test, remove a required element (e.g. type) from the example resource and POST it to $validate again. Expected result: OperationOutcome with an error-severity issue indicating the missing element. This confirms profile validation is actively enforcing constraints.

Profiles to spot-check (at least one per IG):

Step 6. Install other conformance resources

Install SearchParameter and any other resource types excluded from Step 3 that belong on the content repository, such as Subscription or OperationDefinition. See Custom Search Parameters and Customizing Installed Resource Types for details.

{
  "name": "hl7.fhir.us.carin-bb",
  "version": "2.1.0",
  "installMode": "INSTALL_ONLY",
  "installResourceTypes": ["SearchParameter", "Subscription"],
  "additionalResourceFolders": ["example"],
  "fetchDependencies": true
}

Repeat for each of the four packages listed in Step 3.

GET {CONTENT_FHIR}/SearchParameter?name=ExplanationOfBenefit-type

GET {CONTENT_FHIR}/ExplanationOfBenefit?patient=Patient/Patient1
GET {CONTENT_FHIR}/ExplanationOfBenefit?type=professional
GET {CONTENT_FHIR}/ExplanationOfBenefit?service-date=ge2026-01-01