FHIR Extension Builder

Design and validate FHIR extensions with proper URLs and value types. Free, browser-based, no signup.

  • Build valid FHIR extensions with correct URLs, value[x] types, and nesting.

How to build a FHIR extension

  1. Enter the extension URL, the canonical URL of the StructureDefinition that defines it. Or quick-load a common one: US Core race, ethnicity or birth sex.
  2. Choose simple (one value[x]) or complex (nested sub-extensions, each with its own url and value).
  3. Pick the value type (string, code, boolean, integer, decimal, dateTime, uri, Coding, CodeableConcept, Reference and others) and enter the value.
  4. Copy or download the generated JSON and add it to the extension array of your resource or element.

Everything runs in your browser.

Simple vs complex extensions

A simple extension has a URL and exactly one value:

{
  "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex",
  "valueCode": "F"
}

A complex extension has no value of its own, only nested extensions. Their urls are short names relative to the parent:

{
  "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-race",
  "extension": [
    {
      "url": "ombCategory",
      "valueCoding": { "system": "urn:oid:2.16.840.1.113883.6.238", "code": "2106-3", "display": "White" }
    },
    { "url": "text", "valueString": "White" }
  ]
}

An extension can have a value *or* nested extensions, never both (invariant ext-1).

Where extensions go

  • On a resource: Patient.extension.
  • On an element: Patient.name[0].extension, or on a primitive via the underscore property:
"birthDate": "1987-02-20",
"_birthDate": {
  "extension": [{ "url": "http://hl7.org/fhir/StructureDefinition/patient-birthTime", "valueDateTime": "1987-02-20T14:35:00-06:00" }]
}
  • modifierExtension is for extensions that change the meaning of the element, such as negating it. Receivers that don't understand a modifier extension must not process the element, so use it only when the data would be misread without it.

Before you invent an extension

  1. Check whether the base resource already has an element for it. Use the Resource Inspector or the R4 and R5 references.
  2. Check published extensions: the FHIR core extensions registry and the implementation guide you follow (US Core, IPS and others).
  3. If you still need your own, use a URL you control (https://yourorg.example/fhir/StructureDefinition/...) and publish a StructureDefinition there, so others can learn what it means.

Limitations

  • The builder produces the extension instance. It doesn't create the StructureDefinition that formally defines a new extension.
  • It doesn't check the URL against published definitions, or check that the value type matches what the definition allows. Validating against the profile with the HL7 validator does that.

FAQ

Do extension URLs need to resolve?

They should identify a StructureDefinition, and resolving to it is good practice, but validators can only check extensions whose definitions they've loaded. Unknown extensions usually produce a warning, not an error.

Is my data sent anywhere?

No. The extension JSON is generated in this page.

Which FHIR versions does it support?

Extensions have the same structure in R4, R4B and R5. Some value types differ between versions (R5 allows a few more, such as integer64), so check that the receiver's version supports the type you choose.

How do I add an extension to a primitive such as birthDate?

Primitives can't hold child elements in JSON, so FHIR uses a sibling property with an underscore: "_birthDate": { "extension": [ ... ] }, as shown above.

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.