Creating FHIR Resources from Scratch: Patient, Encounter and a Blood Pressure Observation
Build a linked FHIR R4 Patient, Encounter and blood pressure Observation step by step, with the reasoning for each element and the R5 differences.
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.
Copying an example from the specification works until you need to change it. This tutorial builds three resources from an empty object: a Patient, an Encounter for a clinic visit, and a blood pressure Observation taken during it. Along the way it explains *why* each element looks the way it does. The examples are FHIR R4 (4.0.1), with R5 differences called out where they matter.
Rules that apply to every resource
resourceTypeis required and is the exact, case-sensitive type name.idis assigned by the server on create. Leave it out when you POST. Include it only for PUT (update or create-with-id) and inside Bundles you control.- No empty values. Never write
"",[],{}ornull. Omit the element instead. - Codes carry their system. A
Codingwithout asystemis just a string nobody else can interpret. - Check cardinality. Elements marked
0..*are arrays even when they hold one item.
Step 1: the Patient
Start with identity. An identifier is the business identifier you'll match on later (MRN, national id), namespaced by system:
{
"resourceType": "Patient",
"identifier": [
{
"use": "usual",
"type": {
"coding": [{ "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "MR", "display": "Medical record number" }]
},
"system": "http://hospital.example.org/mrn",
"value": "00123456"
}
],
"active": true,
"name": [
{ "use": "official", "family": "Shaw", "given": ["Amy", "V."] }
],
"telecom": [
{ "system": "phone", "value": "+1-555-0100", "use": "mobile" },
{ "system": "email", "value": "amy.shaw@example.com" }
],
"gender": "female",
"birthDate": "1987-02-20",
"address": [
{ "use": "home", "line": ["49 Meadow St"], "city": "Mounds", "state": "OK", "postalCode": "74047", "country": "US" }
]
}
Why it looks like this:
identifier.systemis a URI *you* control that names the namespace of the MRN. It doesn't need to resolve; it needs to be stable and unique to your organization.nameis an array because people have several names: official, maiden, nickname.givenis an array too, because a person can have several given names.genderis administrative gender with a required binding:male | female | other | unknown, lowercase. Birth sex and gender identity are separate concepts that implementation guides capture with extensions (such as US Core's birth sex extension, shown below).birthDateis adate, so it takes no time and no timezone. Partial dates (1987or1987-02) are allowed when that's all you know.
Step 2: the Encounter
An Encounter records the visit itself. It links to the Patient through subject:
{
"resourceType": "Encounter",
"status": "finished",
"class": {
"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
"code": "AMB",
"display": "ambulatory"
},
"type": [
{
"coding": [{ "system": "http://snomed.info/sct", "code": "185349003", "display": "Encounter for check up" }]
}
],
"subject": { "reference": "Patient/example" },
"period": {
"start": "2026-03-05T09:30:00-06:00",
"end": "2026-03-05T09:55:00-06:00"
}
}
statushas a required binding. In R4, a completed visit isfinished.classin R4 is a singleCoding, usually from the v3 ActCode system:AMB(ambulatory),EMER,IMP(inpatient),VR(virtual).periodusesdateTimevalues with times, so they must include a timezone offset.
The same Encounter in R5
R5 changed several of these elements, which is the most common source of "unknown element" errors when R4 code meets an R5 server:
| R4 | R5 |
|---|---|
status: "finished" | status: "completed" |
class — one Coding | class — array of CodeableConcept |
period | actualPeriod |
hospitalization | admission |
reasonCode / reasonReference | reason (with use and value as CodeableReference) |
Step 3: the blood pressure Observation
Blood pressure is a good example because it shows components: one Observation that holds two values.
{
"resourceType": "Observation",
"status": "final",
"category": [
{
"coding": [{ "system": "http://terminology.hl7.org/CodeSystem/observation-category", "code": "vital-signs", "display": "Vital Signs" }]
}
],
"code": {
"coding": [{ "system": "http://loinc.org", "code": "85354-9", "display": "Blood pressure panel with all children optional" }],
"text": "Blood pressure"
},
"subject": { "reference": "Patient/example" },
"encounter": { "reference": "Encounter/example-visit" },
"effectiveDateTime": "2026-03-05T09:40:00-06:00",
"component": [
{
"code": { "coding": [{ "system": "http://loinc.org", "code": "8480-6", "display": "Systolic blood pressure" }] },
"valueQuantity": { "value": 128, "unit": "mmHg", "system": "http://unitsofmeasure.org", "code": "mm[Hg]" }
},
{
"code": { "coding": [{ "system": "http://loinc.org", "code": "8462-4", "display": "Diastolic blood pressure" }] },
"valueQuantity": { "value": 82, "unit": "mmHg", "system": "http://unitsofmeasure.org", "code": "mm[Hg]" }
}
]
}
Element by element:
statusis required (registered | preliminary | final | amended | ...). Downstream systems often ignore anything that isn'tfinaloramended.category: vital-signsis required by the base specification's vital signs profile. Servers that enforce it reject vitals without it.codesays *what* was measured. The LOINC panel code85354-9is the parent; systolic8480-6and diastolic8462-4go in the components.- No top-level
value[x]: the values live incomponent. That's allowed because the panel itself has no single value. effective[x]is when the measurement applies clinically. That isn't the same asissued, which is when it was made available.valueQuantityuses UCUM:systemhttp://unitsofmeasure.organdcodemm[Hg].unitis just display text; systems compute withcode.
Single-value observations
Most observations have a single value instead of components. A heart rate looks like this:
"code": { "coding": [{ "system": "http://loinc.org", "code": "8867-4", "display": "Heart rate" }] },
"valueQuantity": { "value": 72, "unit": "beats/minute", "system": "http://unitsofmeasure.org", "code": "/min" }
If a value is missing (the patient refused, the device failed), leave out value[x] and add dataAbsentReason instead. The spec forbids having both (invariant obs-6).
Step 4: send them together
The Encounter and Observation reference resources that don't exist on the server yet. Rather than three calls and hand-copying ids, wrap all three in a transaction Bundle with urn:uuid placeholders, as shown in FHIR Bundle Types Explained. The server assigns ids and rewrites the references atomically.
Adding an extension
When the base resource has no element for something you need, use an extension: a URL that defines it, plus a value.
"extension": [
{
"url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex",
"valueCode": "F"
}
]
Prefer published extensions (from the specification or an implementation guide such as US Core) to inventing your own. If you must define one, host its StructureDefinition under a URL you control.
Mistakes to check before you send
| Mistake | Fix |
|---|---|
"name": { "family": "Shaw" } | name is 0..*: wrap it in an array |
"gender": "F" | Use female |
"effectiveDateTime": "2026-03-05T09:40:00" | Add a timezone: ...09:40:00-06:00 or Z |
"valueQuantity": { "value": "128" } | Numbers are JSON numbers, not strings |
"code": { "coding": [{ "code": "8867-4" }] } | Add "system": "http://loinc.org" |
Both valueQuantity and valueString | Only one value[x] per element |
"middleName": "" from a mapper | Omit empty values |
Try it
Paste each resource into the FHIR Validator as you build it. It has detailed rules for Patient and Observation and line-mapped errors. Use the Extension Builder to compose extensions, and the Resource Inspector to look up any element's type and cardinality in R4 or R5.
Standards and references
- FHIR R4: Patient
- FHIR R4: Encounter
- FHIR R5: Encounter
- FHIR R4: Observation
- FHIR R4: Vital signs profile
- FHIR R4: Extensibility
- UCUM (units of measure)
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.