FHIR Validation Best Practices: The Five Layers and the Errors You'll Actually See
What valid FHIR really means: syntax, structure, invariants, terminology and profiles. How to validate each layer, and fixes for the most common errors.
By the FHIR Toolbox team, Omindra Labs · 6 min read ·
Checked against the official specifications listed under Standards and references at the end of this article.
"Is this valid FHIR?" has no single answer. A resource can be perfectly well-formed JSON, match the base specification, and still be rejected because it breaks a US Core profile rule or uses a code that isn't in the required value set. Good validation means knowing which layer you're checking and choosing the right tool for each.
The five layers of validation
| Layer | Question it answers | Example failure |
|---|---|---|
| 1. Syntax | Is it parseable JSON? | Trailing comma, unquoted key |
| 2. Structure | Do elements, types and cardinality match the resource definition? | "gender": ["female"], unknown element birthdate |
| 3. Invariants | Do the FHIRPath constraints in the spec hold? | Observation with both value[x] and dataAbsentReason |
| 4. Terminology | Are codes from the right systems and value sets? | "status": "Final" (codes are case-sensitive) |
| 5. Profiles | Does it meet an implementation guide's extra rules? | US Core Patient without identifier |
On top of these sits business validation — "this patient already exists", "the encounter end is after discharge" — which no FHIR validator can do for you.
Layer 1 and 2: syntax and structure
Most errors in hand-built or mapped data are structural. The rules that trip people up:
- No empty values.
"",[]and{}are not allowed anywhere. Leave the element out instead. Mappers that emit"middleName": ""for every blank CSV cell fail here. - Arrays vs single values. Cardinality
0..*means an array even for one item:"name": [{ ... }], never"name": { ... }. Cardinality0..1means a single value, never an array. - Primitives have formats.
idis 1–64 characters ofA-Z a-z 0-9 - ..dateisYYYY,YYYY-MMorYYYY-MM-DD. AdateTimethat includes a time must include a timezone:2024-03-05T14:30:00Zor2024-03-05T14:30:00-05:00, never2024-03-05T14:30:00. - Booleans and numbers are JSON types.
"active": "true"and"value": "72"are strings and therefore invalid. - Element names are case-sensitive.
birthdateis an unknown element; the element isbirthDate. - Only one choice type.
value[x]becomes exactly one ofvalueQuantity,valueString,valueCodeableConceptand so on, never two.
Layer 3: invariants
The specification attaches constraints to resources and data types, written in FHIRPath. A few you'll meet:
| Key | Resource | Rule |
|---|---|---|
obs-6 | Observation | dataAbsentReason only if there's no value[x] |
pat-1 | Patient | A contact needs a name, telecom, address or organization |
bdl-3 | Bundle | entry.request is required for batch/transaction/history and prohibited otherwise |
ele-1 | All elements | Every element must have a value or children |
dom-6 | DomainResource | A resource should have narrative (a warning, not an error) |
obs-6, for example, is literally the expression dataAbsentReason.empty() or value.empty(). You can paste it into the FHIRPath playground against your Observation to see why it fails.
Layer 4: terminology
Every coded element has a binding to a value set with a strength:
- required — the code *must* come from the value set (e.g.
Observation.status,Patient.gender). - extensible — use a code from the value set if one fits; otherwise you may use another.
- preferred / example — guidance only.
Required bindings on code elements are where most terminology errors come from. "gender": "F" and "status": "Final" are both invalid because the codes are female and final. For CodeableConcept bindings, the validator needs a terminology server to check codes from large systems like SNOMED CT or LOINC. Offline validators can usually only check that a system URI is present and well-formed.
Layer 5: profiles
Implementation guides like US Core add constraints on top of the base resource: required elements (mustSupport, minimum cardinality), fixed values, slicing and extra invariants. A resource declares the profiles it claims to conform to in meta.profile:
"meta": {
"profile": ["http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"]
}
Claiming a profile in meta.profile doesn't make the resource conform. It tells the validator what to check against.
Choosing a validator
The official HL7 validator
The reference implementation, published by HL7 as a Java jar. It checks all five layers and is what certification test tools are built on:
java -jar validator_cli.jar patient.json -version 4.0.1
java -jar validator_cli.jar patient.json -version 4.0.1 -ig hl7.fhir.us.core#6.1.0
java -jar validator_cli.jar ./examples/*.json -version 4.0.1 -output results.json
It downloads packages and uses tx.fhir.org for terminology by default, so it needs network access. Add -tx n/a to run offline without terminology checks. The same engine powers the web UI at validator.fhir.org.
A server's $validate operation
Many servers (HAPI, Firely, Azure, Google Cloud Healthcare) expose validation as an operation:
POST [base]/Patient/$validate
Content-Type: application/fhir+json
{ "resourceType": "Patient", ... }
Add ?profile=http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient to validate against a profile the server has loaded. The result is an OperationOutcome. Note that each server validates to its own configuration, so results can differ from the HL7 validator.
Fast in-editor checks
For the quick loop of "did I break the structure?", a lightweight in-browser check is faster than starting a JVM. The FHIR Toolbox Validator checks JSON syntax, resourceType, id and meta for any resource. It adds detailed element, type, code and cardinality rules for Patient, Observation and Bundle, including the resources inside a Bundle. It doesn't do terminology or profile validation, so use the HL7 validator before you claim conformance.
Reading an OperationOutcome
Every serious validator reports problems as an OperationOutcome:
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "value",
"diagnostics": "The value 'Final' is not in the required value set http://hl7.org/fhir/ValueSet/observation-status",
"expression": ["Observation.status"]
},
{
"severity": "warning",
"code": "informational",
"diagnostics": "Constraint failed: dom-6: 'A resource should have narrative for robust management'",
"expression": ["Observation"]
}
]
}
severity:fatalanderrormust be fixed;warningdeserves a look;informationis advisory.expressionis a FHIRPath location — the fastest way to find the offending element.- Fix errors from the top: one structural error (a wrong type high in the tree) often causes a cascade of follow-on errors below it.
Building validation into your workflow
- Validate at the boundary. Check data where it enters your system (mapping output, inbound API calls), not only before sending it on.
- Pin the version. Validate against the exact FHIR version (4.0.1, 4.3.0, 5.0.0) and IG version you target. Mixing R4 and R5 elements is a frequent cause of "unknown element" errors.
- Validate examples in CI. Run the HL7 validator over your sample payloads and fixtures on every change. Breaking a mapping should fail a build, not a partner's integration.
- Track warnings. Warnings like missing narrative or unknown extensions often become errors in the next IG version.
- Treat validator differences as information. If the HL7 validator and your server disagree, the server's configuration (loaded profiles, terminology) is usually the reason.
Try it
Paste a resource into the FHIR Validator to see line-mapped errors and warnings, then use the Resource Inspector to check an element's type, cardinality and definition. For the common structural mistakes above, see Creating FHIR Resources from Scratch.
Standards and references
- FHIR R4: Validating resources
- FHIR R4: Data types and primitive formats
- FHIR R4: OperationOutcome
- FHIR R4: Terminologies and binding strengths
- HL7 FHIR Validator (web)
- US Core Implementation Guide
FHIR Toolbox is a free collection of HL7 FHIR tools by Omindra Labs. The tools process your data in your browser; it is not uploaded for normal tool operations.