Navigating FHIR standards starts with accepting that FHIR is not one standard but a stack: a base specification, national profiles, security guides, data-access patterns and domain guides, each with its own versions. A team that picks the wrong layer, or the wrong version of the right one, builds an API nobody can call.
This guide sorts the stack by the question each layer answers, shows how to read the conformance rules that matter, and ends with a decision list by product type.
How do you choose which FHIR standards to build against?
Unsure which FHIR guides your product needs?
Agnotic builds FHIR and SMART on FHIR software for clients, starting from the standards your partners actually support.
Choosing FHIR standards means working from your partners and use case outward. Pick the base FHIR version your partners run, the national profile set they conform to, the security guide that governs access, any data-access pattern such as Bulk Data, and only then the domain guides your use case requires. Confirm each choice against partner capability statements.
A common mistake is the reverse order: starting from the newest or most interesting guide and hoping partners catch up. In US exchange, partners move on regulatory timelines, so the floor they share matters more than the ceiling any one of them reaches.
Which layers make up a FHIR standards stack?
A FHIR standards stack has five layers, and each answers a different design question. Keeping them separate makes it easier to see which choice a partner constraint affects.
- Base specification: which resources, data types, search rules and REST interactions exist, set by the FHIR release such as R4.
- National profiles: which elements must be present and which codes to use in a country, such as US Core in the United States.
- Security: how an app or system gets authorized and what it may access, set by SMART App Launch and related guides.
- Data-access patterns: how large or event-driven data moves, such as Bulk Data export for populations or Subscriptions for change notices.
- Domain guides: how a specific workflow works on top of the rest, such as the Da Vinci guides for payer and provider exchange.
Terminology runs through every layer. Profiles bind elements to value sets from LOINC, SNOMED CT, RxNorm and others, so a terminology service is part of the stack even though it is not a FHIR guide.
Which base FHIR version should a US product use?
A US product should build on FHIR R4, version 4.0.1, because the guides that govern US exchange are built on it. Later releases are worth tracking, but leading with them means translating back to R4 for every US partner.
Keep the version visible in code. Put the FHIR version and each guide's package version in configuration, and resolve profiles from those packages rather than from copied JSON files. That makes a later upgrade a planned change rather than a hunt through the codebase.
If a product also serves other countries, treat each national profile set as a separate target on the same base version where possible. The International Patient Summary guide is one example of a cross-border profile set that some programs adopt.
Why does US Core set the floor for US work?
US Core sets the floor because ASTP/ONC certification ties the standardized EHR API to it. The (g)(10) Standardized API criterion requires certified EHRs to serve USCDI data through US Core profiles, so any app or system that reads from a certified EHR meets US Core first.
US Core publishes new versions regularly. HL7 lists US Core 9.0.0 (STU 9), built on FHIR 4.0.1, as the current published version, but a given certified EHR may conform to an earlier release. Build to the version your partners certify against, and read the change log between that version and the current one so you know what is coming.
What Must Support means in practice
Must Support in US Core places obligations on both sides. The guide says US Core Responders shall be capable of populating all Must Support data elements, and US Core Requestors must process resources containing them without failing, though they may choose not to use data that does not meet their needs.
Missing data has its own rules. When a responder has no data and does not know why, it omits the element; when it knows why, it may send a data absent reason. Requestor code should treat a missing element as data the responder does not have, not as a negative finding.
Watch for elements flagged as additional USCDI requirements. They are needed for certification, so certifying systems treat them as Must Support, while other implementers may treat them as optional. An app that relies on such an element, such as race or ethnicity, should expect it from certified EHRs and handle its absence elsewhere.
How do SMART App Launch and Bulk Data fit in?
SMART App Launch governs how apps and systems get authorized, and Bulk Data governs how populations of records are exported. Both sit alongside US Core rather than inside it.
HL7 lists SMART App Launch 2.2.0, built on FHIR 4.0.1, as the current published version. It defines EHR launch and standalone launch for user-facing apps, scopes for patient, user and system access, and backend services authorization for system-to-system clients that run without a user.
Choose the launch type from who is using the product. A clinician tool embedded in the EHR uses EHR launch with user scopes. A patient app uses standalone launch with patient scopes. A nightly analytics job uses backend services with system scopes and usually calls Bulk Data export.
Bulk Data export runs asynchronously: the client starts an export, polls a status endpoint and downloads newline-delimited JSON files. Design for large files, retries and partial failures, and confirm with each site which groups and resource types it allows.
Backend clients also need key management. Backend services authorization uses a signed assertion from the client's private key, so plan key rotation, the published key set and what happens when a site rejects a key, before the first scheduled export.
When do Da Vinci and other domain guides apply?
Domain guides apply when the product takes part in a specific workflow that a guide defines. They build on US Core, so they add requirements without replacing the floor.
- Da Vinci prior authorization guides (CRD, DTR, PAS): coverage requirements discovery, documentation templates and prior authorization submission between providers and payers. CMS recommends them for CMS-0057-F APIs but does not require them.
- Da Vinci PDex and the CARIN guide for consumer-directed exchange: payer data shared with providers, other payers and members.
- Specialty guides such as mCODE for oncology: richer clinical profiles for programs that need them.
- Questionnaire-based guides such as SDC: structured forms and data capture that other guides, such as DTR, build on.
Adopt a domain guide only when a partner asks for it or a workflow needs it. Each one adds profiles, test cases and versioning work, and a guide nobody exchanges with is maintenance with no return.
Pin domain guide versions the same way as US Core. Domain guides often depend on a specific US Core release, so upgrading one without the other can break validation. Read each guide's dependency list before agreeing a version with a trading partner, and keep the agreed versions in the interface contract.
Reading a server's conformance before writing code
A FHIR server states what it supports, and reading that statement first prevents many surprises. Every FHIR server publishes a CapabilityStatement at its metadata endpoint, and SMART servers publish their authorization details at a well-known configuration URL.
In the CapabilityStatement, check the FHIR version, the guides it says it implements, the supported profiles for each resource type, the search parameters and interactions allowed, and any operations such as Bulk Data export. In the SMART configuration, check the supported launch types, scopes and token endpoint authentication methods.
Treat the statement as a starting claim, then test it. The HL7 FHIR validator checks resources against profiles, and Inferno test kits check servers against US Core and the certification API. Results that disagree with the CapabilityStatement go back to the partner before you code around them.
A standards decision list by product type
This list gives a starting stack for common product types. Adjust it after reading each partner's conformance statements.
- 1. Clinician app inside the EHR: FHIR R4, the US Core version your EHR partners certify against, SMART App Launch EHR launch with user scopes.
- 2. Patient-facing app: FHIR R4, US Core, SMART App Launch standalone launch with patient scopes, plus payer Patient Access APIs if claims data is in scope.
- 3. Analytics or population health system: FHIR R4, US Core, SMART backend services and Bulk Data export, with a plan for large file handling.
- 4. Payer or prior authorization product: FHIR R4, US Core, the Da Vinci guides your trading partners use, and the CMS-0057-F API set.
- 5. New product with its own FHIR API: FHIR R4, US Core profiles for shared data, your own profiles only for data US Core does not cover, and a published CapabilityStatement.
- 6. Every product: a terminology service, the FHIR validator in the build pipeline, and a written record of each guide version in use.
How Agnotic can help
Choosing a FHIR stack is quick to get wrong and slow to unwind once partners depend on it. Agnotic Technologies builds FHIR and SMART on FHIR software for clients, starting with partner conformance checks and a written standards decision, then building to it: US Core mapping, SMART authorization, Bulk Data pipelines, domain guide support and validation in the build pipeline.
Agnotic can also review an existing FHIR build against its partners' current conformance statements, list where it falls behind or overreaches, and plan the upgrade path to newer US Core and SMART App Launch versions without breaking live connections.
Choose and build your FHIR stack with Agnotic
Explore Agnotic's FHIR development services, or browse the FHIR articles hub.
Related reading on Agnotic
Continue with FHIR versions, implementation guides, US Core, SMART scopes and FHIR-ready architecture.
