Extension Navigation With FHIRPath: The ext(url) Shortcut

Extensions are how FHIR carries what the base spec did not model, and navigating them is one of the most common FHIRPath tasks. The verbose form works but reads long; the .extension(url) shortcut is idiomatic and shorter. Learning both is the payoff-heavy investment. The site's FHIRPath live tryout is where the two forms get exercised side by side. For the wider FHIR framing, more on healthcare data exchange collects related material.

The Verbose Form

Patient.extension.where(url = 'http://hl7.org/fhir/StructureDefinition/us-core-race').value — the fully-spelled path to the value of the us-core-race extension on a Patient.

Reading it: navigate to the extension collection, filter to the one whose url matches, extract the value. Every step is explicit, and the verbosity is the readable version.

The Shortcut Form

Patient.extension('http://hl7.org/fhir/StructureDefinition/us-core-race').value — the same thing, half the characters. The .extension(url) function is a FHIRPath idiom that combines the collection filter and the extension key lookup into one call.

Not every engine implements the shortcut. Standards-compliant ones do; older or minimalist ones may not. Test against your target evaluator before committing to it.

Nested Extensions

Some extensions are complex — they carry sub-extensions. US Core race has ombCategory, detailed, and text sub-extensions. The nested navigation follows the same pattern:

`` Patient .extension('http://hl7.org/fhir/StructureDefinition/us-core-race') .extension('ombCategory') .value ``

Each nested extension level is another .extension() call keyed by url or short name. For the memorized set of expressions, typical FHIRPath expressions worth memorizing covers the surrounding idioms.

The Value Polymorphism

Extension value[x] is polymorphic. It can be a string, a Coding, a Quantity, a Reference, a boolean, or one of many types. .value returns whatever type the extension carries.

Downstream code has to handle the polymorphism. .value.ofType(Coding) narrows to just Coding-typed values. .value.ofType(string) narrows to strings. That is where the shortcut hits its usefulness — the compact form makes the type-narrow step readable.

Modifier Extensions Live on modifierExtension

The base spec has two extension arrays: extension[] and modifierExtension[]. Both are navigable the same way. For modifier extensions, the path starts at modifierExtension:

Patient.modifierExtension.where(url = 'http://example.com/ext/dnr').value

Reading a modifier extension out means the receiver has to handle it. Ignoring modifier extensions on receipt is not compliant, and the invariant that catches missing handling should test both arrays.

When The URL Has a Version Suffix

Canonical URLs sometimes carry version suffixes: http://example.com/StructureDefinition/us-core-race|3.1.1. Extension arrays in real payloads may or may not include the version. A filter that matches the exact URL fails on version-suffixed entries.

The safe pattern: filter on the URL prefix, or normalize the URL before matching. For safe invariants that survive this drift, using FHIRPath in invariants without shooting yourself in the foot covers the pattern.

Common Real-World Extensions

us-core-race on Patient — race categories
us-core-ethnicity on Patient — ethnicity categories
us-core-birthsex on Patient — birth sex
us-core-birthplace on Patient — birthplace address
us-core-genderIdentity on Patient — gender identity

Each has a well-known URL and a documented structure. The tryout lets you paste a real US Core Patient and step through the extension reads live.

Collection Semantics Still Apply

.extension(url) returns a collection. If the extension is not present, the collection is empty. If two extensions share the url — rare, but possible — the collection has both. Chaining .value after it works even on empty results. For the collection semantics, the collection semantics that surprise you at first is the entry.

The Short Version

.extension(url) is the shortcut for the verbose where(url = ...) filter. Nested extensions chain the same pattern. Watch value polymorphism and version-suffixed URLs. Practice both forms in the tryout against a US Core Patient with a full extension set.