Healthcare: Clinical Timestamps
HL7 International calls HL7 version 2 “one of the most widely implemented standards for healthcare information in the world” (HL7 product list). The date-time in a version 2 message is not ISO 8601. The number of digits says how precise the value is, and the offset is optional. A reader that takes a value without an offset for UTC moves every event by the offset of the place that sent it, and a reader that pads a year to a moment states a fact nobody sent.
FHIR R4 is the other standard a clinical system meets. Its date, dateTime and instant are
profiles of ISO 8601, and they differ from HL7 version 2 on the point that matters most: a FHIR
time must carry a zone, so there is no sender’s local time to guess.
There are three functions for each standard. For HL7, parseHL7 reads a value, formatHL7
writes one and isValidHL7 checks one. For FHIR, parseFHIR, formatFHIR and isValidFHIR do
the same. Each takes a string and returns a string, an object or a boolean, and none of them
throws. A call the types accept returns the sentinel (null, "" or false) when the value is
wrong. The HL7 sections come first, and FHIR R4 follows
them.
import { parseHL7 } from "@northguild/gmt/healthcare/parse";import { formatHL7 } from "@northguild/gmt/healthcare/format";import { isValidHL7 } from "@northguild/gmt/healthcare/validate";Each function has a page in the healthcare reference, with a playground that runs it.
HL7 version 2: DTM and TS
Section titled “HL7 version 2: DTM and TS”The standard names two types. DTM is the date-time. TS is the older time stamp, a DTM
followed by a degree of precision. The degree is kept only for backward compatibility, and
version 2.6 withdrew TS. HL7’s own chapters call them 2.A.22 and 2.A.77, and the degree 2.A.77.2
(headed 2.A.1.22, 2.A.1.77 and 2.A.1.77.2 in the hl7.eu copy of version 2.5.1).
The four kinds
Section titled “The four kinds”parseHL7 returns one of four kinds, or null for a value it does not read.
| Kind | When | Members |
|---|---|---|
"instant" | a minute or finer, with an offset | instant, offset, local, precision |
"local" | a minute or finer, no offset | local, precision |
"partial" | year, month, day or hour, or cut to one by a TS degree | local, offset, precision |
"null" | the null value "" | none |
import { parseHL7 } from "@northguild/gmt/healthcare/parse";
parseHL7("20240615103000+0300");// { kind: "instant", instant: "2024-06-15T07:30:00Z", offset: "+03:00",// local: "2024-06-15T10:30:00", precision: "second" }parseHL7("20240615103000");// { kind: "local", local: "2024-06-15T10:30:00", precision: "second" }parseHL7("20240615");// { kind: "partial", local: "2024-06-15", offset: "", precision: "day" }parseHL7('""');// { kind: "null" }parseHL7("2024-06-15");// nullThe type makes you check kind before you read instant. Only the "instant" kind has one.
Precision is the number of digits
Section titled “Precision is the number of digits”The picture in 2.A.22 is YYYY[MM[DD[HH[MM[SS[.S[S[S[S]]]]]]]]][+/-ZZZZ], and the standard says
“The number of characters populated (excluding the time zone specification) specifies the
precision”. The digits sent are the precision.
| Digits sent | Precision |
|---|---|
| 4 | "year" |
| 6 | "month" |
| 8 | "day" |
| 10 | "hour" |
| 12 | "minute" |
| 14 | "second" |
| 14, a point, 1 to 4 | "fraction" |
local is written at the precision sent, so an hour is 2024-06-15T10 and no minute is added.
From the minute on, seconds are always written, so a minute reads as 10:30:00. At most four
fraction digits are read, and the fraction is kept as it was sent.
parseHL7("2024061510");// { kind: "partial", local: "2024-06-15T10", offset: "", precision: "hour" }parseHL7("202406151030");// { kind: "local", local: "2024-06-15T10:30:00", precision: "minute" }parseHL7("20240615103000.1234");// { kind: "local", local: "2024-06-15T10:30:00.1234", precision: "fraction" }parseHL7("20240615103000.12345");// nullThe offset that is not there
Section titled “The offset that is not there”2.A.22 says “if the time zone is not included, the time zone defaults to that of the local time
zone of the sender”. A value with no offset is the sender’s local time, so the "local" kind
has no instant. Appending Z would state a place the message never named.
An offset is + or - and four digits. +0000 and -0000 both mean UTC and both read as
+00:00. The standard restricts offsets to “legally-defined time zones” but names no list, so
any hour from 00 to 23 and minute from 00 to 59 is read.
parseHL7("20240615103000+0000");// { kind: "instant", instant: "2024-06-15T10:30:00Z", offset: "+00:00",// local: "2024-06-15T10:30:00", precision: "second" }parseHL7("20240615103000-0000");// { kind: "instant", instant: "2024-06-15T10:30:00Z", offset: "+00:00",// local: "2024-06-15T10:30:00", precision: "second" }parseHL7("20240615103000+0530");// { kind: "instant", instant: "2024-06-15T05:00:00Z", offset: "+05:30",// local: "2024-06-15T10:30:00", precision: "second" }From a local time to an instant
Section titled “From a local time to an instant”When the message names no offset, you know the zone and GMT does not. Pass the local member and
the sending facility’s IANA zone to resolveLocal:
import { parseHL7 } from "@northguild/gmt/healthcare/parse";import { resolveLocal } from "@northguild/gmt/instant/convert";
const result = parseHL7("20240615103000");if (result?.kind === "local") { resolveLocal(result.local, "Europe/Helsinki"); // "2024-06-15T07:30:00Z"}A wall time can fall in an hour the zone skips or repeats. resolveLocal takes a
disambiguation option for those, and its reference page
says what each value does. "reject" returns "" instead of choosing:
resolveLocal("2024-03-31T03:30:00", "Europe/Helsinki"); // "2024-03-31T01:30:00Z" — 03:30 was skipped; the default, "compatible", takes the later readingresolveLocal("2024-03-31T03:30:00", "Europe/Helsinki", { disambiguation: "reject" }); // ""resolveLocal("2024-10-27T03:30:00", "Europe/Helsinki"); // "2024-10-27T00:30:00Z" — 03:30 happened twice; "compatible" takes the earlier readingresolveLocal("2024-10-27T03:30:00", "Europe/Helsinki", { disambiguation: "later" }); // "2024-10-27T01:30:00Z" — 03:30 happened twiceresolveLocal("2024-10-27T03:30:00", "Europe/Helsinki", { disambiguation: "reject" }); // ""A partial value names a span
Section titled “A partial value names a span”1965 is a birth year. It is not 1 January 1965 at midnight, and padding it to a moment states a
fact the sender did not send. A "partial" value keeps its precision and has no instant. It keeps
an offset when one was sent with it.
parseHL7("1965");// { kind: "partial", local: "1965", offset: "", precision: "year" }parseHL7("196506");// { kind: "partial", local: "1965-06", offset: "", precision: "month" }parseHL7("20240615-0500");// { kind: "partial", local: "2024-06-15", offset: "-05:00", precision: "day" }TS and its degree of precision
Section titled “TS and its degree of precision”A TS is a DTM, then ^, then one of Y L D H M S (year, month, day, hour, minute, second).
The degree only lowers the precision. 2.A.77.2 says it “is either the same as or overrides the
precision indicated by the first component. It may not indicate greater precision”.
parseHL7("199904011200^L");// { kind: "partial", local: "1999-04", offset: "", precision: "month" } — April 1999parseHL7("20240615103000.1234^S");// { kind: "local", local: "2024-06-15T10:30:00", precision: "second" } — the fraction is cutparseHL7("20240615^S");// null — a second is finer than the day sentparseHL7("20240615^");// { kind: "partial", local: "2024-06-15", offset: "", precision: "day" } — an empty degree is absentparseHL7("20240615^D^");// { kind: "partial", local: "2024-06-15", offset: "", precision: "day" } — so is an empty third componentA field read on its own carries no MSH-2, so parseHL7 takes the separators Figure 2-1
recommends: ^ between components and & between subcomponents (ch. 2 §2.5.4). A feed whose
MSH-2 names others re-joins the field with ^ and & before it calls parseHL7.
A receiver ignores “components, subcomponents, and extra repetitions of a field that are present
but were not expected” (ch. 2 §2.6.2), and a later version of HL7 adds components at the end of a
data type (§2.8.1, §2.8.2). So a third component, and anything after it, is not read, unless it
holds a |, a ~ or a control character: those end the field, the repetition or the segment, so
the text is not one field and parseHL7 returns null. GMT reads the first two components more
strictly than §2.6.2 asks: each is exactly one value, so a & inside the date-time or the degree
returns null. A component left empty is not present, so an empty DTM returns null.
parseHL7("20240615^D^X");// { kind: "partial", local: "2024-06-15", offset: "", precision: "day" } — the third component is ignoredparseHL7("20240615^D^X&Y");// { kind: "partial", local: "2024-06-15", offset: "", precision: "day" } — a & in an ignored component is ignored tooparseHL7("2024&X");// null — a subcomponent inside the date-timeparseHL7("20240615^D^X|Y");// null — a | ends the field, so this is more than one fieldMidnight is the start of the day
Section titled “Midnight is the start of the day”2.A.22 gives 198807050000 as “Midnight of the night extending from July 4 to July 5, 1988”, so
0000 is the start of the stated day. Hour 24 and second 60 are refused.
parseHL7("198807050000");// { kind: "local", local: "1988-07-05T00:00:00", precision: "minute" }parseHL7("2024061524");// nullparseHL7("20240615103060");// nullThe null value
Section titled “The null value”A field that holds two double quotes ("") is the null value. It clears a stored value, and
chapter 2 says it “is different from omitting an optional data field”. parseHL7 returns it as
its own kind. An empty string is not the null value and returns null. Never treat one as the
other.
parseHL7('""'); // { kind: "null" }parseHL7(""); // nullWriting a DTM
Section titled “Writing a DTM”formatHL7 takes an ISO 8601 value and writes a DTM. It writes the offset the value has, and
Z writes +0000. It never writes a TS. The precision is the one the input is written in, and
the precision option only lowers it. It cuts and never rounds, so a fraction of .98765 is
written as .9876.
import { formatHL7 } from "@northguild/gmt/healthcare/format";
formatHL7("2024-06-15T10:30:00"); // "20240615103000"formatHL7("2024-06-15T10:30"); // "202406151030"formatHL7("2024-06-15T10:30:00Z"); // "20240615103000+0000"formatHL7("2024-06-15T10:30:45.98765-05:00"); // "20240615103045.9876-0500"formatHL7("2024-06-15T10:30:45.5Z", { precision: "minute" }); // "202406151030+0000"A "local" value read at minute precision comes back from parseHL7 with :00 seconds, so
writing it with the digits it was sent with takes the precision parseHL7 returned. A
"partial" value with an offset has no ISO input form, because 2024-06-15-05:00 is not ISO
8601. Write it from the instant, at the precision you want:
const r = parseHL7("202406151030");if (r?.kind === "local") { formatHL7(r.local); // "20240615103000" — seconds added formatHL7(r.local, { precision: r.precision }); // "202406151030" — the digits sent}formatHL7("2024-06-15T10:30:00-05:00", { precision: "day" }); // "20240615-0500"formatHL7("2024-06-15-05:00"); // "" — not ISO 8601formatHL7 returns "" when it cannot write the value without changing it: an offset with
seconds, a year outside 0000–9999, a reduced ISO form with an offset, an annotation of any kind (a time
zone is not read: write the wall clock with its offset) and a precision finer than the input.
formatHL7("2024-06-15T10:30:00+05:30:15"); // "" — the offset has secondsformatHL7("+010000-01-01T00:00:00"); // "" — the year is outside 0000–9999formatHL7("2024-06-15T10:30:00Z[Europe/Helsinki]"); // "" — an annotation is not readformatHL7("2024-06-15T10:30:00", { precision: "fraction" }); // "" — there is no fraction to writeCheck before reading
Section titled “Check before reading”isValidHL7 is parseHL7(value) !== null, so the two cannot disagree. The null value is valid.
import { isValidHL7 } from "@northguild/gmt/healthcare/validate";
isValidHL7("20240615103000"); // trueisValidHL7("199904011200^L"); // trueisValidHL7('""'); // trueisValidHL7(""); // falseisValidHL7("20240615^S"); // falseWhat is not read
Section titled “What is not read”These return null from parseHL7 and false from isValidHL7: a separator other than ^
and &, an empty DTM, a lower-case degree, a leap second, more than four fraction digits and
ISO 8601 extended form (2024-06-15T10:30:00).
parseHL7("20240615~D"); // nullparseHL7("^D"); // null — the DTM is emptyparseHL7("20240615^l"); // nullparseHL7("2024-06-15T10:30:00"); // null — ISO 8601 is the input of formatHL7The exported types
Section titled “The exported types”Hl7DateTime is the result of parseHL7.
Its precision is an Hl7PartialPrecision, year to
hour, for a "partial" value and an Hl7MomentPrecision,
minute to fraction, for an "instant" or "local" one.
Hl7Precision is the two together, and
Hl7FormatOptions is the options of
formatHL7.
FHIR R4: date, dateTime and instant
Section titled “FHIR R4: date, dateTime and instant”FHIR R4 Datatypes §2.24.0.1 defines three primitive types that carry a date. HL7 publishes one
regular expression for each in the R4 StructureDefinitions, and GMT exposes them as fhirDate,
fhirDateTime and fhirInstant in @northguild/gmt/regex. The notes in §2.24.0.1 call them
“informative, not normative”, so they are a first filter and not a check.
import { parseFHIR } from "@northguild/gmt/healthcare/parse";import { formatFHIR } from "@northguild/gmt/healthcare/format";import { isValidFHIR } from "@northguild/gmt/healthcare/validate";Three types, one grammar
Section titled “Three types, one grammar”parseFHIR reads a value of any of the three types and returns the value as sent, its precision
and its offset. isValidFHIR and formatFHIR take the type as their second argument, because the
type decides which precisions are allowed.
| Precision | Example | Allowed in |
|---|---|---|
"year" | 2024 | date, dateTime |
"month" | 2024-06 | date, dateTime |
"day" | 2024-06-15 | date, dateTime |
"second" | 2015-02-07T13:28:17-05:00 | dateTime, instant |
"fraction" | 2015-02-07T13:28:17.239Z | dateTime, instant |
A second value is YYYY-MM-DDThh:mm:ss and a zone. A fraction value adds a decimal part to the
seconds.
parseFHIR("2015-02-07T13:28:17-05:00");// { value: "2015-02-07T13:28:17-05:00", precision: "second", offset: "-05:00" }parseFHIR("2024-06-15T10:30:00.5+02:00");// { value: "2024-06-15T10:30:00.5+02:00", precision: "fraction", offset: "+02:00" }
isValidFHIR("2024-06-15T10:30:00Z", "instant"); // trueisValidFHIR("2024-06-15", "instant"); // false — an instant is a second or finerisValidFHIR("2024-06-15T10:30:00Z", "date"); // false — a date has no timeThere is no hour or minute precision in FHIR: a time always carries seconds. A fraction of more than nine digits is refused, not cut short, because Temporal holds nanoseconds.
Precision is kept
Section titled “Precision is kept”2024-06 is a month. It is not midnight on 1 June, and padding it states a day and a time the
sender did not send. parseFHIR returns the value as it was sent, with nothing added.
parseFHIR("2024");// { value: "2024", precision: "year", offset: "" }parseFHIR("2024-06");// { value: "2024-06", precision: "month", offset: "" }parseFHIR("2024-6-15");// null — the month is not paddedComparing one partial value with another is a different problem. FHIRPath defines it in its
Equality and
Comparison sections, and GMT does not compare partial
values. Use a FHIRPath engine for that, and use parseFHIR to read each value first.
A time needs a zone
Section titled “A time needs a zone”HL7 version 2 reads a time with no offset as the sender’s local time. FHIR does not allow one:
§2.24.0.1 says that “if hours and minutes are specified, a time zone SHALL be populated”. So a
FHIR time with no zone is not a local time to resolve later. It is invalid, and parseFHIR
returns null for it.
parseFHIR("2024-06-15T10:30:00"); // null — no zoneparseFHIR("2024-06-15T10:30"); // null — no seconds, and no zoneparseFHIR("2024-06-15T24:00:00Z"); // null — 24:00 is not allowedisValidFHIR("2024-06-15T10:30:00", "dateTime"); // falseThe zone is Z or ±hh:mm from -14:00 to +14:00. Z, +00:00 and -00:00 all read as
offset: "+00:00", and value keeps the spelling that was sent. Compare offset, not the
strings.
parseFHIR("2024-06-15T10:30:00Z");// { value: "2024-06-15T10:30:00Z", precision: "second", offset: "+00:00" }parseFHIR("2024-06-15T10:30:00-00:00");// { value: "2024-06-15T10:30:00-00:00", precision: "second", offset: "+00:00" }parseFHIR("2024-06-15T10:30:00+14:30"); // null — past +14:00Leap seconds
Section titled “Leap seconds”FHIR allows a second of 60: “Leap Seconds are allowed” in §2.24.0.1. GMT accepts it only on an
inserted leap second, at any offset spelling. 2016-12-31T23:59:60Z was a real second, and
2017-12-31T23:59:60Z was not.
isValidFHIR("2016-12-31T23:59:60Z", "instant"); // trueisValidFHIR("2017-12-31T23:59:60Z", "instant"); // false — no second was inserted that dayparseFHIR("2016-12-31T18:59:60-05:00");// { value: "2016-12-31T18:59:60-05:00", precision: "second", offset: "-05:00" } — the same secondThe patterns prove shape only
Section titled “The patterns prove shape only”fhirDate, fhirDateTime and fhirInstant accept strings that isValidFHIR refuses. A match
says the value has the right shape, not that it is a real date or a real second.
import { fhirDateTime, fhirInstant } from "@northguild/gmt/regex";
fhirDateTime.test("2024-02-30"); // true — there is no 30 FebruaryisValidFHIR("2024-02-30", "dateTime"); // false
fhirInstant.test("2017-12-31T23:59:60Z"); // true — a second of 60 on any dayisValidFHIR("2017-12-31T23:59:60Z", "instant"); // false
fhirInstant.test("2024-06-15T10:30:00.1234567890Z"); // true — a fraction of any lengthisValidFHIR("2024-06-15T10:30:00.1234567890Z", "instant"); // false — ten digitsThe other direction holds: a value that isValidFHIR accepts always matches the pattern for its
type. Use the pattern to filter, then isValidFHIR or parseFHIR to decide.
Writing a FHIR value
Section titled “Writing a FHIR value”formatFHIR takes an ISO 8601 value and writes it as a date, dateTime or instant. It reads
the wall clock as written, and it cuts and never rounds, so the result never names a later second,
day or month than the input. The precision option only lowers the precision. A finer one returns
"".
formatFHIR("2024-06-15T23:59:59.999Z", "instant", { precision: "second" }); // "2024-06-15T23:59:59Z" — cut, not roundedformatFHIR("2024-12-31T23:59:59.999-05:00", "dateTime", { precision: "year" }); // "2024"formatFHIR("2024-06", "dateTime", { precision: "day" }); // "" — finer than the value carriesUnder date, the result is the wall-clock date at the input’s own offset, because FHIR forbids a
zone on a date. The designator is written as the input spells it, so Z, +00:00 and -00:00
stay as they were. A second of 60 returns "", because §2.24.0.1 says applications producing
leap seconds “MAY choose to avoid” them.
formatFHIR("2024-06-15T23:30:00-05:00", "date"); // "2024-06-15" — the date where the sender wasformatFHIR("2024-06-15T10:30:00-00:00", "dateTime"); // "2024-06-15T10:30:00-00:00"formatFHIR("2024-06-15T10:30:00", "instant"); // "" — an instant needs a zoneformatFHIR("2016-12-31T23:59:60Z", "instant"); // "" — a leap second is not writtenA time zone annotation is not read: formatFHIR("2024-06-15T23:30:00Z[Europe/Berlin]", "date") is
"". Write the wall clock with its offset instead. An offset that is not a whole number of
minutes, such as +02:00:30, returns "", under date too.
FHIR has no minute precision, and formatFHIR never zero-fills. An HL7 version 2 time at minute
precision therefore gives "" under dateTime and instant. The caller either cuts it to a day
or adds :00 knowingly. parseHL7 already writes :00 into local for a minute value, so look
at precision before you join local and offset.
import { parseHL7 } from "@northguild/gmt/healthcare/parse";import { formatFHIR } from "@northguild/gmt/healthcare/format";
formatFHIR("2024-06-15T10:30-05:00", "dateTime"); // "" — no minute precision in FHIRconst sent = parseHL7("202406151030-0500");if (sent?.kind === "instant" && sent.precision === "minute") { const iso = sent.local + sent.offset; // "2024-06-15T10:30:00-05:00": the :00 is added formatFHIR(iso, "dateTime", { precision: "day" }); // "2024-06-15" // Writing the whole value is right only if a zero second is acceptable. formatFHIR(iso, "dateTime"); // "2024-06-15T10:30:00-05:00"}FhirDateTime is the result of
parseFHIR. Its precision is a FhirPrecision.
FhirDateType is the second argument of isValidFHIR and
formatFHIR, and
FhirFormatOptions is the options
of formatFHIR.
See it break, then work
Section titled “See it break, then work”- An HL7 Time Read as UTC
- A TS Date Read as a Time
- A FHIR Month Padded to Midnight
- Healthcare mistakes, and the FHIR R4 mistakes
- HL7 Timestamp Reader, a tool that reads a value of your own
- FHIR Date Checker, a tool that checks a FHIR
date,dateTimeorinstantof your own
© 2026 NorthGuild · Licences
Code examples: MIT-0. Packages: MIT. Third-party data and components: their own licences, credited where they appear. Everything else: © 2026 NorthGuild, all rights reserved.