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

LayerQuestion it answersExample failure
1. SyntaxIs it parseable JSON?Trailing comma, unquoted key
2. StructureDo elements, types and cardinality match the resource definition?"gender": ["female"], unknown element birthdate
3. InvariantsDo the FHIRPath constraints in the spec hold?Observation with both value[x] and dataAbsentReason
4. TerminologyAre codes from the right systems and value sets?"status": "Final" (codes are case-sensitive)
5. ProfilesDoes 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": { ... }. Cardinality 0..1 means a single value, never an array.
  • Primitives have formats. id is 1–64 characters of A-Z a-z 0-9 - .. date is YYYY, YYYY-MM or YYYY-MM-DD. A dateTime that includes a time must include a timezone: 2024-03-05T14:30:00Z or 2024-03-05T14:30:00-05:00, never 2024-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. birthdate is an unknown element; the element is birthDate.
  • Only one choice type. value[x] becomes exactly one of valueQuantity, valueString, valueCodeableConcept and so on, never two.

Layer 3: invariants

The specification attaches constraints to resources and data types, written in FHIRPath. A few you'll meet:

KeyResourceRule
obs-6ObservationdataAbsentReason only if there's no value[x]
pat-1PatientA contact needs a name, telecom, address or organization
bdl-3Bundleentry.request is required for batch/transaction/history and prohibited otherwise
ele-1All elementsEvery element must have a value or children
dom-6DomainResourceA 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: fatal and error must be fixed; warning deserves a look; information is advisory.
  • expression is 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

  1. Validate at the boundary. Check data where it enters your system (mapping output, inbound API calls), not only before sending it on.
  2. 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.
  3. 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.
  4. Track warnings. Warnings like missing narrative or unknown extensions often become errors in the next IG version.
  5. 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 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.