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

Copy

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.

Option A: Remote terminology server

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.

Option B: Manual upload Download and upload each CodeSystem locally. This is required when pre-expansion with hierarchy filters is needed, or when a remote terminology server is unavailable.

The table below lists external CodeSystems commonly referenced by the IGs installed in Step 3. Not all are required for every use case; load the ones your data actually uses.

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

Copy

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.

3a. Install required IGs

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
}

Copy

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.

3b. Troubleshoot ValueSet expansion failures

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

Copy

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
}

Copy

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.

5a. Verify ValueSet expansion ($expand) Confirm the REST API returns correct expansion results.

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

Copy

Expected result: expansion containing codes such as attending, referring, performing, supervising.

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

Copy

Expected result: expansion containing codes such as clmrecvddate, billingnetworkcontractingstatus.

Repeat with at least one ValueSet from each installed IG, including ValueSets that depend on external CodeSystems uploaded in Step 2. If an expansion returns an error or empty result, investigate using the approach in Step 3. 5b. Verify code validation ($validate-code) Confirm that code validation against installed ValueSets works end-to-end.

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

Copy

Expected result: Parameters with result = true.

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

Copy

Expected result: Parameters with result = false.

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

Copy

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.

5c. Verify code lookup ($lookup) Confirm that $lookup returns display values for installed CodeSystems.

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

Copy

Expected result: Parameters with display = "Claim Received Date" (or similar display text from the CodeSystem).

Repeat with codes from external CodeSystems loaded in Step 2. A successful $lookup with a display value confirms those CodeSystems are loaded and authoritative locally. 5d. Validate resources against profiles ($validate) Use the $validate operation to confirm that profile validation is enforcing constraints from the installed IGs. Pick at least one profile from each installed IG.

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>

Copy

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.

6a. Install SearchParameters Iterate through the same packages and install only SearchParameter resources using the content Package Registry:

PUT``{CONTENT_PKG_REGISTRY}/write/install/by-spec

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

Copy

The optional additionalResourceFolders installs IG-published example resources (Patient, Coverage, ExplanationOfBenefit, etc.) alongside the SearchParameters, which is useful for verifying search in Step 6b because these examples contain real values in the FHIR elements each SearchParameter indexes (e.g. ExplanationOfBenefit.type, ExplanationOfBenefit.billablePeriod), so the Step 6b queries will return matches immediately without loading additional data.

6b. Verify search Before verifying, ensure you have content resources (e.g. Patient, ExplanationOfBenefit, Coverage, Organization) in the content repository. You have two options:

• If you included "additionalResourceFolders": ["example"] in the Step 6a install spec, the IG-published examples are already loaded and no further action is needed.
• Alternatively, upload your own resources (Patient, ExplanationOfBenefit, Coverage, or other resources) via POST or PUT to {CONTENT_FHIR}. Use your own test data or production-representative samples that exercise the fields the SearchParameters index.

Confirm the SearchParameters were installed:

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

Copy

Then search content resources using the installed SearchParameters:

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

Copy

Expected result: the matching resources are returned. If a search parameter returns no results when matches are expected, verify that reindexing has completed.

Consent Tutorial

CMS-0057-F IG Setup Tutorial

Tutorials

Introduction Integration Testing Tutorial Custom Operations Tutorial HL7 v2.x Ingestion Tutorial Federated OAuth2/OIDC Tutorial MDM Tutorial MDM UI Tutorial MDM First Golden Resource Tutorial MDM Advanced Rule Authoring Tutorial MDM Web UI Admin Setup Tutorial CDA Import Tutorial CDA Export Tutorial CDA Export - Custom Narrative Generation Tutorial CDA Import JSON example CDA Export Template JSON example Consent Tutorial CMS-0057-F IG Setup Tutorial