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

  1. resourceType is required and is the exact, case-sensitive type name.
  2. id is 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.
  3. No empty values. Never write "", [], {} or null. Omit the element instead.
  4. Codes carry their system. A Coding without a system is just a string nobody else can interpret.
  5. 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.system is 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.
  • name is an array because people have several names: official, maiden, nickname. given is an array too, because a person can have several given names.
  • gender is 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).
  • birthDate is a date, so it takes no time and no timezone. Partial dates (1987 or 1987-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"
  }
}
  • status has a required binding. In R4, a completed visit is finished.
  • class in R4 is a single Coding, usually from the v3 ActCode system: AMB (ambulatory), EMER, IMP (inpatient), VR (virtual).
  • period uses dateTime values 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:

R4R5
status: "finished"status: "completed"
class — one Codingclass — array of CodeableConcept
periodactualPeriod
hospitalizationadmission
reasonCode / reasonReferencereason (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:

  • status is required (registered | preliminary | final | amended | ...). Downstream systems often ignore anything that isn't final or amended.
  • category: vital-signs is required by the base specification's vital signs profile. Servers that enforce it reject vitals without it.
  • code says *what* was measured. The LOINC panel code 85354-9 is the parent; systolic 8480-6 and diastolic 8462-4 go in the components.
  • No top-level value[x]: the values live in component. That's allowed because the panel itself has no single value.
  • effective[x] is when the measurement applies clinically. That isn't the same as issued, which is when it was made available.
  • valueQuantity uses UCUM: system http://unitsofmeasure.org and code mm[Hg]. unit is just display text; systems compute with code.

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

MistakeFix
"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 valueStringOnly one value[x] per element
"middleName": "" from a mapperOmit 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 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.