The FHIR Implementation Gap: What the Specification Doesn't Tell You About Production

FHIR (Fast Healthcare Interoperability Resources) is the most important standard in healthcare data exchange today. If you read the specification, it's elegant: RESTful APIs, JSON resources, standardized terminology bindings, and a modern authentication framework. On paper, FHIR solves healthcare interoperability.

In production, it's a different story entirely.

After building FHIR integrations across multiple EHR platforms, connecting to health information exchanges, and passing certification testing suites, we've documented nine specific gaps between what the FHIR specification promises and what production healthcare systems actually deliver. These aren't theoretical concerns — they're the problems that cause integration projects to blow past timelines by 3-6 months and the issues that ONC's own interoperability reports consistently identify as barriers to adoption.

This guide documents each gap, provides the real-world data behind it, and gives you the practical solutions we use in production. Whether you're building your first FHIR integration or your fiftieth, these are the things the specification won't teach you.

The Promise vs Reality

The FHIR specification (currently R4, published 2019, with R5 in STU status) describes a world where healthcare data flows seamlessly through RESTful APIs. Resources like Patient, Observation, Condition, and MedicationRequest follow well-defined schemas. SMART on FHIR provides standardized OAuth 2.0 authentication. Implementation Guides (IGs) constrain base resources into profiles that ensure consistent data exchange.

Here's what the specification assumes:

• Single version: Everyone implements the same FHIR version
• Complete data: Resources contain all required and recommended fields
• Consistent behavior: Same API calls produce same results across systems
• Standard auth: SMART on FHIR works identically everywhere
• Clean terminology: Coded values use standard terminologies consistently

Here's the production reality, based on data from the ONC Health IT Dashboard and our own integration experience:

• Multi-version chaos: 38% of production FHIR endpoints still serve DSTU2 or STU3 data alongside R4 (SMART Health IT research, 2025)
• Sparse data: Average FHIR resource from production EHRs contains 40-60% of expected fields
• Vendor-specific behavior: The same search query returns different results on Epic vs Oracle Health vs athenahealth
• Auth variations: Token lifetimes range from 5 minutes (Epic) to 60 minutes (athena), breaking stateless architectures
• Terminology gaps: Only 40% of SNOMED CT concepts have exact ICD-10-CM mappings (NLM UMLS Mapping Project)

The gap between specification and production is where integration projects fail. Let's walk through each one.

Gap 1: The Many-to-Many Problem

The FHIR specification describes a clean interaction model: your application connects to a FHIR server, exchanges resources, and processes responses. The tutorials show one client talking to one server running one version of FHIR.

Production healthcare integration looks nothing like this.

The Version Matrix

A typical healthcare SaaS product connecting to US health systems in 2026 must handle:

• Epic: FHIR R4 (since August 2020), with some organizations still on STU3 for specific modules
• Oracle Health (Cerner): R4 (since 2021), with legacy Millennium endpoints on DSTU2
• athenahealth: R4 (late adopter), with limited resource coverage compared to Epic
• MEDITECH Expanse: R4 (Expanse only — legacy MEDITECH has no FHIR)
• Allscripts/Veradigm: Mixed STU3/R4 depending on product line
• VA VistA: FHIR R4 via Lighthouse API, but with significant data model differences

When you're connecting to 50+ health systems, you're not building one integration — you're building a compatibility matrix. Each EHR has different resource coverage, different supported search parameters, different extension patterns, and different data quality characteristics.

The N:N Reality

In production, your application talks to N different FHIR servers, each running M different versions with P different profiles. This creates combinatorial complexity that the specification doesn't address:

// What the spec shows:
GET /Patient/123 -> Patient resource

// What production requires:
GET /Patient/123
  -> Check CapabilityStatement for FHIR version
  -> Detect if R4 or STU3 (field names differ)
  -> Handle vendor-specific extensions
  -> Normalize to internal data model
  -> Validate against expected US Core profile
  -> Log data quality metrics per source

Solution: Build a normalization layer between your application and EHR FHIR endpoints. This layer should: (1) query and cache each server's CapabilityStatement, (2) maintain per-vendor adapters that handle version differences, (3) normalize all data to your internal model before it reaches business logic, and (4) track data quality metrics per source system. We've found this adds 2-3 months to initial development but saves 6+ months of per-vendor debugging downstream.

Gap 2: Implementation Guide Chaos

FHIR's extension mechanism is a feature, not a bug — it allows the base specification to be adapted for specific use cases. But the result is an ecosystem of over 1,000 Implementation Guides that create a landscape almost impossible to navigate.

The Registry Problem

The FHIR IG Registry lists implementation guides, but it doesn't answer the question every developer asks: "Which IGs do I need for my use case?"

For a typical US healthcare application handling patient data exchange, you need to understand and potentially implement:

• US Core 7.0: The base US profiles mandated by ONC, with 23 profiles and 6 extensions
• USCDI v4: The data class definitions that drive US Core (26 new data elements in v4)
• SMART App Launch 2.0: OAuth 2.0 authorization with granular scopes
• Bulk Data Access 2.0: Async export for population-level data
• Da Vinci suite: 20+ IGs for payer-provider data exchange (HRex, PDex, PAS, CRD, DTR)
• C-CDA on FHIR: Bridge IG for organizations still using CDA documents

These IGs overlap. US Core profiles are constrained by USCDI requirements. Da Vinci HRex extends US Core. mCODE (oncology) further constrains US Core profiles. QI Core (quality measures) extends US Core differently than mCODE does. When two IGs constrain the same resource differently, which profile wins?

Version Independence

Each IG versions independently. US Core 7.0 was released in late 2024. Da Vinci PDex is on STU 2.0. SMART App Launch is on 2.0 but many EHRs still implement 1.0. Your application must handle:

• US Core 3.1.1, 4.0.0, 5.0.1, 6.1.0, and 7.0.0 (all in production use)
• SMART 1.0 and 2.0 (scope syntax changed between versions)
• Bulk Data 1.0 and 2.0 (export parameters differ)

Solution: Create an IG dependency map for your use case before writing code. Document which profiles you'll validate against, which IGs you'll implement, and which IG versions each of your target EHRs supports. Treat IG compliance as a compatibility matrix, not a single standard. We maintain a living spreadsheet per product that maps target EHR + IG version + supported features, and review it quarterly.

Gap 3: US Core "Must Support" Ambiguity

US Core is the foundation for US healthcare FHIR exchange, mandated by the ONC Cures Act Final Rule. Its profiles use the "Must Support" flag to indicate which data elements are important. But "Must Support" means different things depending on who you are.

The Definition Problem

From the US Core specification, "Must Support" means:

• For servers (EHRs): If the system has the data, it SHALL be included in the response. But it does NOT mean the system must have the data.
• For clients (apps): The application SHALL be able to process the element without error. It does NOT mean the element will always be present.

This creates a fundamental ambiguity. A Patient resource with "Must Support" on race and ethnicity means Epic will send race data if it has it, but athenahealth might not have it at all. Your application must handle both cases, but there's no reliable way to know in advance which fields will be populated for a given patient at a given site.

Production Impact

In our experience integrating with 40+ healthcare organizations:

• Race/Ethnicity: Present in 72% of Epic records, 45% of Oracle Health records, 30% of athenahealth records
• Preferred Language: Present in 60% of Epic records, 35% across other EHRs
• Previous Name: Rarely populated outside of Epic (less than 10%)
• Birth Sex vs Gender Identity: Birth Sex populated consistently; Gender Identity support varies wildly

The ONC USCDI+ data shows that while 96% of hospitals have certified EHR technology, data completeness for USCDI data classes ranges from 95% (demographics) to less than 20% (social determinants of health).

The "Missing Data" Pattern

// What you might expect:
{
  "resourceType": "Patient",
  "extension": [
    {
      "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-race",
      "extension": [
        {"url": "ombCategory", "valueCoding": {"code": "2106-3", "display": "White"}}
      ]
    }
  ]
}

// What you often get (completely valid per spec):
{
  "resourceType": "Patient",
  "name": [{"family": "Smith", "given": ["John"]}]
  // No race extension. No ethnicity extension. No preferred language.
  // This is 100% compliant with US Core.
}

Solution: Design your data model to treat every FHIR field as nullable, regardless of "Must Support" status. Build data completeness dashboards that track field population rates per source system. Use this data to set realistic expectations with product teams about what information will actually be available. We've found that showing product managers a per-source data completeness heatmap eliminates 80% of "why is this field empty?" tickets.

Gap 4: SMART on FHIR Auth in the Wild

SMART on FHIR (Substitutable Medical Applications, Reusable Technologies) is the standard authorization framework for FHIR applications. The specification describes an OAuth 2.0-based flow with well-defined scopes, launch contexts, and token management.

In production, every major EHR implements SMART on FHIR differently enough to break your application.

Epic-Specific Behaviors

Epic is the most mature SMART on FHIR implementer, supporting both SMART 1.0 and 2.0. But their implementation has characteristics that catch every new developer:

• 5-minute token lifetime: Epic access tokens expire in 5 minutes (300 seconds). Most OAuth libraries default to 1-hour tokens. If your token refresh logic checks at 50% lifetime, that's 2.5 minutes — tight for any multi-step workflow.
• Mandatory App Gallery: Production apps must be registered in the Epic App Orchard (now App Market). Sandbox registration is separate. The review process takes 2-8 weeks.
• Granular v2 scopes: Epic supports patient/Observation.rs (read + search) format. If you send v1 scopes (patient/Observation.read), it works but you get a deprecation warning.
• Context-dependent scopes: EHR launch provides launch scope and a launch token. Standalone launch requires launch/patient. Get these wrong and the token endpoint returns a generic 400 with no useful error.

Oracle Health (Cerner) Quirks

• SMART 1.0 primarily: Most Oracle Health (Cerner) Millennium instances still use SMART 1.0 scopes. Their documentation references 2.0 but production implementations lag.
• Non-standard scope names: Some Cerner instances use system/Patient.read while others use system.Patient.read (dot vs slash). The spec says slash, but Cerner's implementation predates the clarification.
• Manual registration: No self-service app registration portal equivalent to Epic's. Registration requires coordination with each health system's Cerner admin.

athenahealth Gotchas

• Limited backend services: System-level access (backend services, or SMART Backend Services) is severely restricted. Most integrations must use user-facing OAuth flows.
• Scope restrictions: athena doesn't support all FHIR resources through SMART scopes. Some resources are only available through their proprietary API.
• Rate limiting: More lenient than Epic but with less predictable behavior. Burst limits aren't documented.

Solution: Build a SMART configuration layer that stores per-EHR auth parameters: token endpoint, authorize endpoint, token lifetime, supported scopes, PKCE requirement, and refresh behavior. Never hardcode any auth parameter. We maintain a YAML configuration file per EHR vendor that gets loaded at connection time, and we test the full auth flow monthly against each production endpoint to catch silent changes.

Gap 5: Terminology Binding Nightmares

FHIR resources use coded data types extensively. A Condition resource uses SNOMED CT or ICD-10-CM for the condition code. An Observation uses LOINC for the observation type. A Medication uses RxNorm for the drug. The specification defines which terminology systems are preferred for which fields.

Production is far messier.

The Mapping Problem at Scale

According to the NLM's SNOMED CT to ICD-10-CM mapping project:

• ~40% of SNOMED CT concepts have exact 1:1 mappings to ICD-10-CM
• ~35% have 1-to-many mappings, requiring clinical context to select the correct ICD-10 code
• ~25% have no direct mapping, requiring approximate or "broader" code selection

This means that when an EHR sends you a Condition resource with a SNOMED code and you need to present an ICD-10 code (for billing, reporting, or analytics), you're facing a non-trivial translation problem 60% of the time.

Version Drift

Terminology systems version independently:

• SNOMED CT: US Edition releases every March and September (2 releases/year)
• ICD-10-CM: Annual update every October 1 (fiscal year alignment)
• LOINC: Releases 2-3 times per year
• RxNorm: Monthly updates

When SNOMED adds concepts in March but ICD-10 doesn't update until October, there's a 7-month window where new SNOMED codes have no ICD-10 mapping. Production systems sending these codes will break any downstream system that requires ICD-10.

EHR-Specific Terminology Practices

• Epic: Uses internal "Epic Condition" codes alongside SNOMED/ICD. The FHIR API may return Epic's internal code as the primary coding and SNOMED as an alternate, or vice versa, depending on organization configuration.
• Oracle Health: Historically used internal Cerner Millennium codes. FHIR APIs expose these as additional codings, but the order of codings in the array is not guaranteed.
• Lab Results: LOINC is the standard for lab observations, but some EHRs still send local lab codes without LOINC mappings, particularly for esoteric tests.

Solution: Build a terminology service that: (1) accepts any coding from any system, (2) attempts translation to your preferred terminology, (3) falls back to broader codes when exact mapping doesn't exist, (4) logs all untranslatable codes for manual review, and (5) version-pins terminology releases so your production mappings don't change unexpectedly. We run terminology updates through a staging environment with automated regression tests before promoting to production.

Gap 6: FHIR Search — The Spec Nobody Implements Fully

FHIR defines a rich search API with support for string matching, date ranges, token searches, reference chaining, includes, reverse includes, composite parameters, and more. It's one of the most powerful parts of the specification.

It's also the part that EHRs implement least consistently.

What Actually Works Across EHRs

Based on testing against production endpoints from Epic, Oracle Health, athenahealth, and MEDITECH:

Universally Supported (>90% of EHRs):

• Patient?name=Smith — Basic string search
• Patient?birthdate=1990-01-01 — Exact date match
• Patient?identifier=|12345 — Identifier search
• Observation?patient=Patient/123 — Reference search
• Condition?patient=Patient/123&category=problem-list-item — Token search

Partially Supported (40-70%):

• Observation?date=ge2024-01-01&date=le2024-12-31 — Date ranges
• _sort=-date — Sort (single parameter)
• _count=50 — Page size control
• Condition?clinical-status=active — Clinical status filtering

Rarely Supported (<25%):

• _include=Observation:patient — Include referenced resources
• _revinclude=Provenance:target — Reverse includes
• _has:Observation:patient:code=8867-4 — Chained reverse search
• _filter — Advanced filter expressions
• _text / _content — Full-text search
• Multiple _sort parameters — Multi-column sort
• Composite search parameters — Combined searches

The CapabilityStatement Gap

In theory, you can query a server's CapabilityStatement to discover which search parameters are supported. In practice:

• CapabilityStatements are often incomplete or inaccurate
• Some EHRs list parameters as "supported" that actually return errors
• Search parameter behavior changes between EHR versions without CapabilityStatement updates
• Custom search parameters are rarely documented in the CapabilityStatement

Solution: Build a search parameter testing harness that runs against each EHR endpoint and maps actual supported parameters. Start with the simplest possible queries and add complexity only when needed. Design your query strategy around the least-capable EHR in your target set. Use _include and _revinclude as optimizations, not requirements — always have a fallback that makes separate requests.

Gap 7: Bulk Data Export — The Last Mile Problem

The FHIR Bulk Data Access specification defines an async pattern for exporting large datasets. You POST a $export request, poll for completion, then download NDJSON files. Simple in concept.

In production, bulk export is where simple specifications meet operational reality.

The Timeout Problem

Bulk exports from large health systems can take hours. A system with 500,000 patients and 5 years of clinical data might generate exports that:

• Take 4-8 hours to complete for a full system export
• Generate 50-200 GB of NDJSON data across hundreds of files
• Timeout silently if the export job exceeds the server's maximum job duration
• Fail partially — some resource types complete while others error out

The specification defines status polling (GET on the content-location URL), but it doesn't specify:

• Maximum job duration before timeout
• Retry behavior after failure
• Whether partial results are available if the job fails
• Maximum file size or file count limits

Incremental Export Challenges

The _since parameter enables incremental exports (only changes since a timestamp). But:

• Not all EHRs support _since reliably
• The timestamp granularity varies (some support seconds, others only dates)
• Deleted resources may or may not appear in incremental exports
• Back-dated changes (data entered today with an effective date in the past) may not appear in _since-based exports

Error Recovery

When a bulk export fails midway:

• Epic provides detailed error files alongside completed data
• Oracle Health returns a generic 500 with minimal diagnostic information
• Some systems delete all export artifacts when any part fails
• Retry logic must handle idempotency — restarting an export may duplicate data

Solution: Build a robust export orchestration layer that: (1) tracks export jobs with states (requested, in-progress, partial, complete, failed), (2) implements exponential backoff polling with configurable maximum wait times, (3) downloads and validates files incrementally as they become available, (4) maintains a checkpoint system so failed exports can resume rather than restart, and (5) runs data integrity checks comparing export counts to expected totals. For large deployments, we recommend Group-level exports over system-level exports for better reliability and faster completion times.

Gap 8: Extensions and Profiles — When Standard Isn't Standard Enough

FHIR's extensibility model is its greatest strength and its most persistent source of interoperability friction. The base resources are intentionally minimal — the "80% use case" — with extensions handling everything else.

The Extension Proliferation Problem

In production, you'll encounter:

• Standard extensions: Defined in IGs like US Core (e.g., us-core-race, us-core-ethnicity)
• Vendor extensions: Epic, Oracle Health, and other EHRs define their own extensions for data that doesn't fit base FHIR resources
• Organization extensions: Individual health systems may add custom extensions for local data needs
• De facto standard extensions: Extensions that multiple vendors use with the same semantics but different URLs

A real-world Patient resource from Epic might contain 15-20 extensions. Some are US Core standard. Some are Epic-specific (http://open.epic.com/FHIR/StructureDefinition/...). Some are organization-specific. Your application needs to know which extensions contain data you need and which to ignore.

Profile Validation in Practice

The FHIR validator can check resources against profiles, but production validation is nuanced:

• Strict validation rejects real data: Production FHIR resources routinely fail strict US Core validation due to missing "Must Support" elements, non-standard extensions, or terminology binding violations
• Lenient validation misses real errors: If you only validate structure (not terminology bindings or cardinality), you'll accept garbage data
• Performance cost: Full FHIR validation is computationally expensive. Validating every resource at ingestion can add 100-500ms per resource.

// Example: Epic Patient with vendor-specific extensions
{
  "resourceType": "Patient",
  "id": "abc123",
  "extension": [
    {
      "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-race",
      "extension": [{"url": "ombCategory", "valueCoding": {"code": "2106-3"}}]
    },
    {
      "url": "http://open.epic.com/FHIR/StructureDefinition/extension/legal-sex",
      "valueCodeableConcept": {"coding": [{"code": "male"}]}
    },
    {
      "url": "http://open.epic.com/FHIR/StructureDefinition/extension/MyChartStatus",
      "valueString": "Activated"
    }
  ]
}

Solution: Implement a tiered validation strategy: (1) structural validation for all resources (reject malformed JSON/XML), (2) profile validation for critical resources (Patient, Condition, Medication) with warnings instead of rejections for non-critical violations, (3) an extension registry that maps known vendor extensions to your internal data model, and (4) an "unknown extension" log that flags new extensions for developer review. Accept and store extensions you don't understand — you may need them later.

Gap 9: Testing in Sandbox vs Reality

Every FHIR developer's rite of passage: all tests pass in the sandbox. The ONC Inferno test suite shows green. You submit for production access. And then everything breaks.

Why Sandbox Success Doesn't Predict Production Success

• Synthetic data is too clean: Sandbox patients have complete demographics, consistent terminology coding, and well-formed resources. Production patients have missing fields, local codes, and data entry errors.
• Sandbox scale is tiny: A sandbox might have 100 patients. Production has 500,000. Queries that return instantly in sandbox timeout in production.
• Sandbox auth is simplified: Many sandboxes use fixed credentials or skip PKCE validation. Production environments enforce every security requirement.
• Sandbox doesn't rate limit: You won't discover Epic's aggressive rate limiting until you hit production. Sandbox lets you make unlimited requests.
• Sandbox FHIR version is current: Sandboxes run the latest FHIR version. Production instances may be 1-2 versions behind due to upgrade cycles.

The Inferno Gap

Inferno is the ONC-mandated testing tool for (g)(10) certification. Passing Inferno is necessary for certification but not sufficient for production readiness. Inferno tests:

• What it does test: SMART auth flow, resource read/search for US Core profiles, Bulk Data export mechanics, proper HTTP status codes
• What it doesn't test: Multi-EHR compatibility, data quality handling, error recovery, rate limit handling, performance under load, terminology mapping, extension processing, long-running operation resilience

We've seen applications pass all 300+ Inferno tests and then fail catastrophically when connecting to a real Epic production instance because they couldn't handle Epic's 5-minute token expiry or didn't implement proper pagination for large result sets.

Solution: Create a production simulation test suite that goes beyond Inferno: (1) test with intentionally incomplete/malformed resources, (2) simulate rate limiting and token expiry, (3) inject network failures and timeouts, (4) test with resources from multiple FHIR versions, (5) validate behavior with large datasets (10,000+ resources per query), and (6) include EHR-specific edge cases you've documented from production incidents. We maintain a "production chaos" test suite that runs nightly against a staging environment seeded with anonymized production data patterns.

How to Bridge Each Gap

Each gap requires specific architectural decisions. Here's a summary of the bridge patterns we use in production:

The total investment to build these bridge patterns is approximately 6-9 months of engineering effort for a team building their first multi-EHR FHIR integration. This is on top of the core integration work itself. Organizations that budget only for "FHIR integration" without accounting for these production gaps consistently exceed timelines by 2-3x.

A FHIR Production Readiness Checklist

Before going live with any FHIR integration, verify every item on this checklist. These represent the minimum requirements we've found necessary for reliable production operation.

Version and Compatibility

• Map all target EHR FHIR versions (document R2/STU3/R4/R4B per endpoint)
• Implement version negotiation using CapabilityStatement
• Test with R4 AND STU3 responses for core resources
• Handle missing optional fields gracefully (no null pointer exceptions)
• Validate against target IG profiles with documented exception handling

Authentication and Security

• Test SMART auth flow end-to-end with each target EHR vendor
• Handle token refresh proactively (before expiry, not after failure)
• Implement PKCE for all public clients
• Support both SMART v1 and v2 scopes
• Cache tokens per-session with proper invalidation

Data Quality and Terminology

• Build a terminology translation layer with fallback chains
• Handle unmapped codes gracefully (log, don't crash)
• Validate all coded fields on ingestion
• Version-pin terminology releases with staged rollouts
• Monitor and alert on mapping failure rates

Search and Query Resilience

• Test each search parameter per EHR endpoint
• Implement fallback queries when parameters are unsupported
• Handle pagination correctly (follow Bundle.link, don't assume page sizes)
• Implement request retry with exponential backoff
• Cache and respect CapabilityStatement responses

Bulk Data and Performance

• Implement async polling with configurable timeout
• Handle partial export failures without data loss
• Build incremental sync using _since with fallback to full export
• Monitor export job completion rates and durations
• Load test with 10x expected data volume

Error Handling and Monitoring

• Parse OperationOutcome for all error responses
• Alert on authentication failures immediately (token issues cascade)
• Track data completeness metrics per source system
• Maintain EHR-specific error playbooks for on-call engineers
• Monitor API response latency at p50, p95, and p99

Conclusion

FHIR is the right standard for healthcare interoperability. The specification is well-designed, the community is active, and adoption is accelerating. But the gap between specification and production is real, measurable, and expensive to bridge.

The nine gaps documented here aren't FHIR's failures — they're the natural consequences of a standard being adopted by a complex, heterogeneous industry. The specification can define how things should work. Only production experience reveals how they actually work.

The organizations that succeed with FHIR are the ones that budget for this gap. They invest in normalization layers, per-vendor adapters, terminology services, and production chaos testing. They treat FHIR as a foundation to build on, not a complete solution to plug into.

If you're building FHIR integrations, bookmark this guide. Refer back to the checklist before each new EHR connection. And if you need help bridging these gaps, we've done it across 40+ health systems — we know where the landmines are.

For more on healthcare interoperability implementation, see our guides on FHIR US Core Implementation, Healthcare Interoperability Standards, and HL7v2 to FHIR Migration.

Frequently Asked Questions

How long does it take to build a production-ready FHIR integration?

A single-EHR integration with basic read access typically takes 2-3 months. A multi-EHR integration that handles the production gaps documented in this guide takes 6-12 months for the first platform, with 2-4 weeks per additional EHR once the normalization layer is built. The critical variable is not the FHIR specification complexity — it's the per-vendor testing and adapter work.

Is FHIR R4 sufficient, or do I need to support R5?

As of March 2026, FHIR R4 remains the production standard in the US, mandated by ONC for (g)(10) certification. R5 is in STU (Standard for Trial Use) status. No major US EHR vendor serves R5 in production. Build for R4, design your data model to be forward-compatible with R5 changes, and plan R5 support for 2027-2028 when EHR vendors begin adoption.

Does passing Inferno testing guarantee my integration will work in production?

No. Inferno validates FHIR specification compliance — correct HTTP methods, proper resource schemas, valid SMART auth flows, and US Core profile conformance. It does not test multi-vendor compatibility, data quality handling, rate limiting resilience, error recovery, or performance under load. Treat Inferno as a necessary certification gate, then build a separate production readiness test suite covering the nine gaps in this guide.

What's the best approach for handling terminology mapping at scale?

Build a centralized terminology service that: (1) maintains versioned mapping tables from NLM's UMLS for SNOMED-to-ICD-10 and LOINC crosswalks, (2) implements a fallback chain (exact match, then narrow-to-broad mapping, then unmapped code logging), (3) runs terminology updates through staging with regression tests before production, and (4) provides analytics on mapping coverage and failure rates per source system. Budget 1-2 months for initial implementation plus ongoing terminology licensing costs (SNOMED CT is free for US use, but tooling isn't).

How should I handle EHR-specific SMART on FHIR differences?

Abstract all auth parameters into a per-EHR configuration layer. Store token lifetimes, scope formats (v1 vs v2), PKCE requirements, refresh token behavior, and registration processes as configuration — never hardcode them. Implement proactive token refresh (refresh at 80% of lifetime, not on 401 response). Test the full auth flow monthly against each production endpoint, because EHR vendors change auth behavior during maintenance windows without notification. Maintain a runbook per EHR with known auth quirks and workarounds.