Skip to main content
FHIR (Fast Healthcare Interoperability Resources) is the HL7 standard that most electronic health records (EHRs) use to exchange clinical data. FHIR Extraction returns standard FHIR R4 JSON. If you have not worked with FHIR before, the output can look verbose. This page explains the five building blocks that make up every response, one at a time, with a small example for each:
  1. Resources: one JSON object per clinical fact
  2. CodeableConcepts: a code plus a label
  3. Choice fields: fields such as onset[x] that can hold different types
  4. References: links from one resource to another
  5. Bundles: the list that holds all resources
For the exact fields of each datatype, see FHIR datatypes. For the rules the endpoint follows when it fills these building blocks, see How FHIR Extraction works.

​
Resources

A resource is one JSON object that describes one clinical fact. Its resourceType field tells you what kind of fact it is. Because every system agrees on the same resource types, field names, and code systems, a resource that one system writes, another system can read.
FHIR defines the fields each resource type may have. The FHIR R4 resource list shows every resource type, and each one has its own page with all its fields, for example Condition. A Condition has clinicalStatus, severity, and bodySite. An Observation has valueQuantity and interpretation. The endpoint only fills a field when the note supports it, apart from the references and a few fixed defaults such as clinicalStatus: active, and leaves out every empty field. Two Condition resources from the same response can therefore have different sets of fields.

​
CodeableConcepts

Most coded fields in FHIR are CodeableConcepts (R4 definition). A CodeableConcept wraps one or more codes in a coding list, plus a human-readable text. Each entry in coding has three parts: A coding from SNOMED CT or LOINC can also carry a version with the version of the code system the endpoint used. The examples in these docs leave it out. Simplified, you can read a CodeableConcept as “code plus label”: 195967001 Asthma. In JSON, it looks like this:
Always compare system and code together. The code 8480-6 means “Systolic blood pressure” in LOINC, but nothing in SNOMED CT.

​
One concept, two codings

Some CodeableConcepts carry two codings for the same meaning. The endpoint puts the FHIR value-set code first, and adds the SNOMED CT equivalent second. For example, a family member’s relationship:
If your system only reads coding[0], it gets the FHIR code. If your system understands SNOMED CT, it can use the second coding.

​
Text-only CodeableConcepts

Some fields describe things that the endpoint does not code, such as the reason for a procedure. Those CodeableConcepts carry only text:

​
Plain codes

A few FHIR fields are not CodeableConcepts but plain strings from a fixed list. Examples are Observation.status ("final"), AllergyIntolerance.criticality ("high"), and Patient.gender ("female"). You read those directly.

​
Choice fields

FHIR writes some fields as onset[x], value[x], or performed[x]. The R4 specification calls these choice elements. The [x] means the field can hold different data types, and the type becomes part of the field name. A resource only ever has one variant. FHIR Extraction uses a date field only when the note states the date as a year or an ISO 8601 date, and falls back to a text field otherwise: Observations use the same pattern for their result: When you read a choice field, check each variant you support, for example onsetDateTime first and onsetString second.

​
References

Resources point to each other with references (R4 definition). Every clinical resource points to the Patient of the note, with subject or, on AllergyIntolerance and FamilyMemberHistory, patient. Every Condition, Procedure, and Observation also points to the Encounter of the note:
reference names the fullUrl of the Encounter’s entry in the same Bundle, and identifier repeats the Encounter’s business ID, so you can link the resources when you import them. AllergyIntolerance and FamilyMemberHistory carry no encounter reference, because allergies and family history outlast a single visit. R4 defines an optional encounter on AllergyIntolerance, but the endpoint does not fill it. Some references carry only a display name, for example the clinician who asserted a diagnosis:

​
Bundles

A Bundle is a FHIR resource that holds other resources (FHIR R4 Bundle). The endpoint returns a Bundle of type transaction. Each item in entry wraps one resource, and its fullUrl matches the resource’s id, so references between the resources resolve inside the Bundle. Each request tells a FHIR server to create the resource, so you can POST the Bundle as it is to your server:
The order is always the same: Patient, Encounter, then Conditions, AllergyIntolerances, FamilyMemberHistories, Procedures, and Observations.

​
Put it together

Here is a short note and the Condition the endpoint produces from it, first simplified and then as the real JSON.
The real response also carries extension entries that point back to the words in the note. Every value points back to the note explains them.

​
Next steps

How FHIR Extraction works

Learn why codes are positive, and how to read status fields.

FHIR datatypes

Look up every datatype, with its fields and an example.