Anatomy of a Resource (JSON, ids, and metadata)

The common framework every resource shares

Every FHIR resource, whatever its type, is built on the same small scaffold before any type-specific data appears ¹. Four elements form that scaffold:

• resourceType — the type name, such as Patient. In JSON it is the first element and tells a reader exactly what kind of thing this is.
• id — the resource’s logical id, a string that is unique within its type on a given server. The id alone is not the whole address: combined with the server’s base URL and the type, it forms the resource’s address, [base]/Patient/{id} ¹. That address is how other resources point at this one and how a client retrieves it.
• meta — a metadata element carried by the server. Its widely-used parts are versionId (which version of this resource you are looking at), lastUpdated (when the server last changed it), and profile (a list of profiles the resource claims to conform to). A profile claim is an assertion, not a guarantee; it signals which rules the resource intends to follow.
• text — an optional human-readable narrative. It holds a status (for example, whether the narrative was generated from the structured data) plus an XHTML rendering a person can read even if their software ignores the structured fields. This continues the long-standing principle that a human can always read the content of a clinical record ².

These four are the framework. They make a resource self-describing, individually addressable, and versioned — independent of whatever clinical data it carries.

The type-specific data elements

On top of the common framework, each resource type defines its own data elements. For Patient, the stable, widely-known elements include ¹:

• identifier — business identifiers for the patient, such as a medical record number. These are the real-world ids people use, distinct from the logical id.
• name — the patient’s name, expressed using the HumanName data type, which separates parts like family and given rather than storing one opaque string.
• gender — administrative gender, drawn from a fixed set of allowed values.
• birthDate — the date of birth.
• address — one or more postal addresses.

A patient can have more than one identifier, name, or address, which is why the specification has to say how many of each element are allowed.

Element conventions: cardinality, naming, and choice types

FHIR describes each element with a small, consistent vocabulary ¹.

• Cardinality states how many times an element may appear, written as min..max. 0..1 means optional and at most one; 1..1 means exactly one and required; 0..* means optional and repeating (any number). A Patient’s birthDate is 0..1; its name is 0..*.
• Naming is camelCase: resourceType, birthDate, lastUpdated. The first word is lowercase and each later word is capitalized.
• Choice elements allow one value out of several permitted data types. The specification writes these as value[x], and in an actual resource the [x] is replaced by the chosen type’s name — for example valueQuantity or valueString. Only one of the alternatives may be present at a time.

Knowing these conventions lets you read any resource definition, not just Patient, because every type is documented the same way.

Serialization: JSON or XML

A resource is an abstract structure; to move it across a wire it is serialized into a concrete format. FHIR defines two: JSON and XML. The two are losslessly interconvertible — a resource serialized as JSON can be converted to XML and back without losing or changing any information ¹. JSON is the common choice for new web APIs, but the choice is about tooling and taste, not about what the resource means.

A Patient, walked through

Here is a compact Patient resource in JSON:

{
  "resourceType": "Patient",
  "id": "pat-1",
  "meta": {
    "versionId": "3",
    "lastUpdated": "2026-05-20T14:08:00Z"
  },
  "name": [
    {
      "family": "Lee",
      "given": ["Maria"]
    }
  ],
  "gender": "female",
  "birthDate": "1984-07-30"
}

Reading it top to bottom: resourceType declares this is a Patient. The id, pat-1, is the logical id; against a server with base URL https://example.org/fhir this resource lives at https://example.org/fhir/Patient/pat-1. The meta block is server metadata: this is versionId 3, last changed at the given timestamp.

The name element is an array — note the square brackets — because name is 0..*; here it holds a single HumanName with a family of Lee and a given array of Maria. gender carries the administrative value female, and birthDate carries a date. Nothing here is Patient-specific magic: the same framework — type, id, meta, optional narrative — wraps every other resource type you will meet, with only the data elements changing from one type to the next.