FHIR versioning: versionId, ETag, vread and _history in one page

The short answer

In FHIR R4, a resource’s meta.versionId changes each time its content changes, and the server manages it.¹ Each version can be read on its own with vread, at [base]/[type]/[id]/_history/[vid], and all of a resource’s versions with _history.² The version also travels in the HTTP ETag header, such as W/"3", and a create returns a Location header with the new id and version.²

Together these let a client do two things that matter for safety: read back exactly the version its write created, and update only the version it last read, using If-Match, so a concurrent change isn’t silently overwritten.² The catch: versioning is a SHOULD, not a SHALL. Servers may not support it at all.²

The pieces

Version ids are strings the server chooses. The spec says there’s no fixed order for them, so a client can’t assume a later version sorts higher.¹ Compare them for equality, never with “greater than”.

A write and its version

A create, then an update:

Code A request one program sends to another over the web.

POST /fhir/Observation
→ 201 Created
  Location: https://fhir.example/fhir/Observation/123/_history/1
  ETag: W/"1"

PUT /fhir/Observation/123
If-Match: W/"1"
→ 200 OK
  ETag: W/"2"

The Location on the create gives you the exact version you wrote.² Reading that version back with vread and comparing the fields you sent is the simplest way to confirm the server stored what you meant, rather than trusting the status code. Our FHIR write benchmark found 11 of 17 synthetic writes where the status said success and the stored data differed from what the client meant; reading back the reported version is one of the checks that caught some of them.

Reading history

_history works at three levels: one resource ([base]/Observation/123/_history), a type ([base]/Observation/_history) and the whole server ([base]/_history). It returns a Bundle of type history, sorted with the oldest versions last, and including deleted resources.² A vread of a version where the resource was deleted should return 410.²

History answers questions a single read can’t:

• Did someone else write in between? If you updated version 2 and history shows a version 3 you didn’t make, another writer was there.
• Did my retry create a duplicate version? Count the versions your client made.
• Was something deleted? The deleted version is in the list.

Our benchmark’s checklist puts it plainly: count versions, not answers. Overwrites, duplicates and partial Bundles show up in history, not in the resource you wrote.²

Updating only what you read

Without If-Match, the last writer wins. Two clients read version 2; each updates; the second update silently replaces the first. With If-Match, the second update carries W/"2", the server sees the resource is now at version 3, and answers 412 Precondition Failed without updating.²

A server that declares versioned-update in its CapabilityStatement expects clients to send the right version on updates.² For agents, If-Match should be the default on every update: an agent rarely knows who else is writing to the same patient’s record, and a 412 is a cheap, clear signal to read again and decide.

Why this matters for agents

An agent writing to a FHIR server is a client like any other, with two differences. It often retries on its own when something looks wrong, and it summarises what it did in words. Both make versioning more useful, not less. A retry that created a second version, or a second resource, shows up in history even when the agent’s summary says “updated once”. And an agent that sends If-Match gets a clear 412 when a clinician or another system changed the record first, instead of quietly replacing their work. Build both into the agent’s FHIR tool, so the model doesn’t have to remember them.

What versioning doesn’t promise

1. It may not exist. Servers are allowed not to version. Those that don’t must leave meta.versionId out, and should answer 404 when history isn’t available.² Check the CapabilityStatement before you build on it.
2. A no-op update may not create a version. HAPI FHIR JPA, for example, doesn’t create a new version for an update that changes nothing; the setting is on by default.³ A client expecting version 3 will find version 2. That’s correct behaviour, but a check that insists on a new version will raise a false alarm.
3. Version ids aren’t counters. Don’t compute the next one; read it from the response.¹
4. lastUpdated isn’t the version. Version-aware updates don’t depend on it.¹

A checklist for clients and agents

1. Read the CapabilityStatement and note the versioning value.
2. Keep the Location or ETag from every write.
3. Read back that version and compare the fields you sent.
4. Send If-Match on every update; treat 412 as “read again”.
5. Count versions in _history after anything that might have retried.
6. Expect no new version for a no-op update on servers that suppress them.

This is how our own FHIR connector checks writes. Each write is read back at the version the server reported and the fields the agent sent are compared one by one, after dropping what the server adds on its own; an update the server kept at the same version carries a note, and a stale If-Match fails as a version conflict without a retry.⁴ In a run against HAPI FHIR JPA, an update the policy denied never reached the server: HAPI’s own history held exactly the two versions that were let through.⁴ Transactions add their own versioning rules, covered in FHIR transaction vs batch, and the general idea is in the read-back check entry. To try checks like this on a real database in your browser, open the playground; to grade what an agent can reach on your machine, run npx deedglass scan (the grade, explained).

Written with AI assistance and checked against our claims register.