FHIR Interoperability

What is FHIR interoperability?

FHIR interoperability is the ability of two systems to exchange HL7 FHIR resources and interpret them the same way, because both conform to the same implementation guide versions, terminology bindings and search behavior. In the United States that usually means FHIR R4 constrained by US Core, proven with validators and test kits such as Inferno.

The word that matters is conformance. A server claims conformance in its CapabilityStatement, a validator checks resources against profiles, and a test kit checks behavior. When all three agree, a new partner can connect with little custom work.

Why does base FHIR R4 not guarantee interoperability?

Base FHIR is deliberately loose so it can serve every country and care setting. HL7 designs core resources around the elements most implementations need and leaves the rest to extensions and profiles, so most cardinalities, code systems and search parameters stay open.

• Shape: one server may send blood pressure as two Observations while another sends one Observation with systolic and diastolic components. Both are valid base FHIR.
• Codes: a Condition coded only with a local problem list code is valid base FHIR, but a partner cannot use it without a SNOMED CT or ICD-10-CM coding.
• Search: base FHIR defines many search parameters, but it does not require a server to support any particular combination, such as patient plus category plus date on Observation.
• Optional elements: an element with cardinality 0..1 in base FHIR may be essential for a workflow, and nothing in the base specification says a sender must populate it.

A profile closes those gaps for a defined use. It sets cardinality, binds value sets, fixes slices, marks elements as Must Support and lists the searches a server has to answer.

What binding strength tells a sender

Every coded element in a profile has a binding strength, and it decides how much freedom a sender has. FHIR R4 defines four: required, extensible, preferred and example.

• Required: the code must come from the bound value set, with no exceptions.
• Extensible: use a code from the value set if one fits; only if none applies may the sender use another code.
• Preferred: the value set is recommended, but other codes are allowed.
• Example: the value set only illustrates the kind of code expected.

Extensible bindings cause the most arguments between partners, because both sides must agree when no code fits. Record those decisions in the mapping documentation so the next engineer does not reopen them.

How do implementation guides stack on FHIR R4?

Implementation guides build on each other in layers. Each guide is published as a versioned package that declares the packages it depends on, which is how a validator knows exactly which rules to load.

• Base specification: FHIR R4 (4.0.1) defines resources, data types, REST interactions, search and operations.
• Realm guide: US Core constrains R4 resources to represent USCDI data for the United States and names required searches.
• Security and access guides: SMART App Launch defines OAuth 2.0 launch and scopes, and the Bulk Data Access guide defines asynchronous $export.
• Domain guides: the HL7 Da Vinci guides (CRD, DTR, PAS, PDex and others) and CARIN Blue Button build payer workflows, often on top of US Core profiles.
• Local profiles: an organization's own profiles derive from a published guide and add only what its workflow needs, with every extension documented.

Version pinning runs through every layer. A server that claims US Core must say which version, and that version fixes which SMART App Launch and FHIR versions sit underneath. Mixing guide versions without checking their dependencies is a reliable way to fail validation.

Packages have stable identifiers, such as hl7.fhir.us.core for US Core, plus a version number. Recording the identifier and version of every package in one configuration file gives the validator, the test kits and the server the same view of the rules.

Where do US regulations cite FHIR guides?

Federal rules adopt specific guides by version, which turns profile conformance into a requirement for certified developers and impacted payers.

• ONC certification: 45 CFR 170.315(g)(10) requires a standardized read API for patient and population services, and 45 CFR 170.215 lists the adopted FHIR, US Core, SMART App Launch and Bulk Data versions.
• Patient Access API: CMS-9115-F (2020) required impacted payers to offer a FHIR Patient Access API, which has been in place since 2021.
• Payer APIs: CMS-0057-F requires Prior Authorization, Provider Access and Payer-to-Payer APIs from 1 January 2027. CMS recommends the Da Vinci CRD, DTR and PAS guides, but they are not required.
• Security: the HIPAA Security Rule at 45 CFR 164.312 is technology-neutral. It requires audit controls and person or entity authentication, while encryption in transit is addressable; it does not name OAuth or TLS, which come from SMART App Launch and good practice.

The ONC HTI-1 final rule updated the (g)(10) baselines to USCDI v3, US Core 6.1.0 and SMART App Launch 2.0. A developer that certified against earlier versions had to move profiles, scopes and tests together, which is why version pins belong in configuration rather than scattered through code.

What does FHIR interoperability testing check?

Testing checks three things: that each resource conforms to its profile, that the server behaves as its CapabilityStatement claims, and that a real partner can use it. Each needs a different tool.

• Resource validation: the HL7 FHIR Validator loads the target guide packages and checks cardinality, invariants, slices and terminology bindings on each resource.
• Behavior testing: Inferno, the open-source testing platform from ASTP/ONC, runs test kits that exercise searches, SMART launches and Bulk Data exports against a live server. Its (g)(10) kit is the one used for certification.
• Scripted scenarios: FHIR TestScript resources describe repeatable test sequences that a test engine can run against a server.
• Partner testing: HL7 Connectathons and vendor sandboxes expose differences in paging, error handling and reference resolution that a test kit does not cover.

Testing belongs in continuous integration, not certification week. Validate generated resources on every change, run behavior tests nightly against staging, and keep a set of synthetic patients that cover every profile in scope.

Testing a FHIR client, not only a server

Clients need conformance tests too. A SMART app that crashes on an unexpected extension, ignores the next link in a search Bundle or fails when a Must Support element is missing will break in production even against a perfect server.

Point the client at a reference server loaded with the same synthetic patients, include resources that carry unknown extensions and absent data, and confirm the client pages through large result sets and handles an expired token by refreshing it.

A conformance testing checklist

Work through these items in order for each guide a product claims.

• 1. Declare: list each guide and version in the CapabilityStatement, with the profiles and search parameters supported per resource.
• 2. Load: pin the same package versions in the validator configuration used in CI.
• 3. Generate: build synthetic test patients that populate every Must Support element and at least one case where data is absent.
• 4. Validate: fail the build on validator errors and review every warning about terminology bindings.
• 5. Exercise: run the matching Inferno test kit against staging, including required search combinations and SMART scopes.
• 6. Error paths: confirm that bad requests return an OperationOutcome with a useful issue code, not a bare HTTP 500.
• 7. Partner: run the same scenarios against each partner sandbox and record vendor-specific behavior in adapter code, not core logic.
• 8. Re-test: repeat the cycle whenever a guide version, profile or terminology release changes.

Where profile conformance breaks

The same handful of failure points causes most rejected resources and failed partner tests.

• Custom extensions for modeled concepts: inventing an extension for data that a guide already models makes the resource unreadable to standard clients.
• Lost original codes: replacing a local code with a standard one, instead of adding the standard coding beside it, discards information clinicians may need.
• Must Support treated as optional: a server that has the data but never sends it fails the guide, even if each resource validates.
• Unbounded exports: running Bulk Data $export on the same resources as interactive reads slows clinicians during population pulls.
• Silent version drift: upgrading one guide package without its dependencies produces errors that look like data problems.
• Search gaps: a server that supports read by id but not the required search combinations fails behavior tests on the first run.
• Missing references: a resource that points to a Practitioner or Encounter the server cannot return leaves clients with dangling links.
• Undeclared support: a server that handles a search but omits it from the CapabilityStatement looks non-conformant to every client and test kit that reads it.

How Agnotic can help

Profile conformance is easiest to get right at the start of a FHIR build and expensive to retrofit. Agnotic Technologies sets up the guide list, package pins, synthetic patients and CI validation first, then builds the client's FHIR servers, facades and SMART on FHIR apps against that test harness.

Sources

• HL7 FHIR R4: Profiling FHIR
• HL7 International: US Core Implementation Guide
• ASTP/ONC: Standardized API for patient and population services, 45 CFR 170.315(g)(10)
• 45 CFR 170.215: Application programming interface standards
• CMS: Interoperability and Patient Access Final Rule (CMS-9115-F)
• CMS: Interoperability and Prior Authorization Final Rule (CMS-0057-F)
• ASTP/ONC: Inferno testing platform
• 45 CFR 164.312: HIPAA Security Rule technical safeguards