Skip to content

Healthcare mistakes

  • Timestamps in HL7 and FHIR clinical data: a precision set by what is sent, and a time with no offset, which HL7 reads as local time and FHIR refuses.

The healthcare layer reads the date-times of clinical messages. The mistakes around them are the ones a hand-written reader makes: taking a value with no offset for UTC, padding a year to a moment, dropping the precision a time stamp carries, treating the null value as an empty field, reading midnight as the end of the day before, and rounding when writing. FHIR R4 adds its own: padding a month to a moment, sending a time with no zone, trusting the published regex, mishandling a leap second and comparing offsets as strings. Every output shown here is what the code returns.

CRITICAL

Reading an HL7 time with no offset as UTC

HL7 says a time with no offset is the local time of the sender. Appending Z states a place the message never named, and the event moves by the sender's offset. parseHL7 returns a local time with no instant, and resolveLocal joins it to the zone you name.

Wrong

const value = "20240615103000"; // no offset
const iso = value.slice(0, 4) + "-" + value.slice(4, 6) + "-" + value.slice(6, 8) + "T" + value.slice(8, 10) + ":" + value.slice(10, 12) + ":" + value.slice(12, 14) + "Z";
new Date(iso).toISOString();
// "2024-06-15T10:30:00.000Z" — three hours out for a lab in Helsinki

Right

import { parseHL7 } from "@northguild/gmt/healthcare/parse";
import { resolveLocal } from "@northguild/gmt/instant/convert";
parseHL7("20240615103000");
// { kind: "local", local: "2024-06-15T10:30:00", precision: "second" }
resolveLocal("2024-06-15T10:30:00", "Europe/Helsinki");
// "2024-06-15T07:30:00Z"
output 
HIGH

Padding a birth year to midnight on 1 January

A value of four digits names a year, not a moment. Padding it states a day, a time and a place the sender did not send. parseHL7 keeps the precision and returns no instant.

Wrong

const birth = "1965";
new Date(Date.UTC(Number(birth), 0, 1)).toISOString();
// "1965-01-01T00:00:00.000Z" — a day and a time nobody sent

Right

import { parseHL7 } from "@northguild/gmt/healthcare/parse";
parseHL7("1965");
// { kind: "partial", local: "1965", offset: "", precision: "year" }
output 
HIGH

Dropping the degree of precision from a TS

In an older time stamp the letter after the caret says how much of the value to keep. Dropping it reads the full digits as a time the sender did not give at that precision. parseHL7 cuts the value to the degree.

Wrong

const [dtm] = "20240615103000^D".split("^");
dtm.slice(0, 4) + "-" + dtm.slice(4, 6) + "-" + dtm.slice(6, 8) + "T" + dtm.slice(8, 10) + ":" + dtm.slice(10, 12) + ":" + dtm.slice(12, 14);
// "2024-06-15T10:30:00" — the sender said the day

Right

import { parseHL7 } from "@northguild/gmt/healthcare/parse";
parseHL7("20240615103000^D");
// { kind: "partial", local: "2024-06-15", offset: "", precision: "day" }
output 
HIGH

Treating the null value as an empty field

Two double quotes are the null value, and it clears what is stored. It is different from an empty field, which leaves the stored value alone. A reader that strips quotes cannot tell them apart. parseHL7 returns the null value as its own kind and an empty string as null.

Wrong

const value = '""';
value.replace(/"/g, "") === "";
// true — dropped as empty, so the stored time is never cleared

Right

import { parseHL7 } from "@northguild/gmt/healthcare/parse";
parseHL7('""');
// { kind: "null" }
parseHL7("");
// null
output 
MEDIUM

Reading 0000 as the end of the day before

HL7 gives 198807050000 as the midnight of the night that runs from 4 July to 5 July, so 0000 is the start of the stated day. Moving it back to hour 24 of the day before writes a time HL7 does not allow.

Wrong

const day = new Date(Date.UTC(1988, 6, 5));
day.setUTCDate(day.getUTCDate() - 1);
day.toISOString().slice(0, 10) + "T24:00:00";
// "1988-07-04T24:00:00" — the sender said 5 July

Right

import { parseHL7 } from "@northguild/gmt/healthcare/parse";
parseHL7("198807050000");
// { kind: "local", local: "1988-07-05T00:00:00", precision: "minute" }
output 
MEDIUM

Rounding a fraction or the offset when writing

Rounding changes what the sender sent, and carrying the digits without the offset loses the place. formatHL7 writes the offset the value has and cuts the fraction to four digits.

Wrong

const seconds = (45.98765).toFixed(4);
"20240615" + "1030" + seconds;
// "20240615103045.9877" — rounded up, and the offset is gone

Right

import { formatHL7 } from "@northguild/gmt/healthcare/format";
formatHL7("2024-06-15T10:30:45.98765-05:00");
// "20240615103045.9876-0500"
output 
HIGH

Padding a FHIR month or day to a time

A FHIR date can stop at a year, a month or a day. Handing it to new Date, or adding a time to it, states a midnight the sender did not send, and a range check counts the whole period as its first moment. parseFHIR keeps the precision and pads nothing.

Wrong

new Date("2024-06").toISOString();
// "2024-06-01T00:00:00.000Z" — a day, a time and a place nobody sent
new Date("2024-06-15").toISOString();
// "2024-06-15T00:00:00.000Z" — a time and a place nobody sent

Right

import { parseFHIR } from "@northguild/gmt/healthcare/parse";
parseFHIR("2024-06");
// { value: "2024-06", precision: "month", offset: "" }
parseFHIR("2024-06-15");
// { value: "2024-06-15", precision: "day", offset: "" }
output 
CRITICAL

Accepting a dateTime that has no zone

HL7 version 2 leaves a time with no offset to the sender's local time. FHIR does not: if hours and minutes are given, a zone SHALL be given. Appending Z to make it parse invents UTC. parseFHIR returns null, so the sender's error is found and the time is not guessed.

Wrong

const value = "2024-06-15T10:30:00"; // no zone
new Date(value + "Z").toISOString();
// "2024-06-15T10:30:00.000Z" — a place the resource never named

Right

import { parseFHIR } from "@northguild/gmt/healthcare/parse";
import { isValidFHIR } from "@northguild/gmt/healthcare/validate";
parseFHIR("2024-06-15T10:30:00");
// null
isValidFHIR("2024-06-15T10:30:00", "dateTime");
// false
output 
HIGH

Treating the R4 regex as validation

HL7 calls the published regexes informative, and says they may allow a broader set of values than are valid. They accept 30 February. isValidFHIR reads the value as well as its shape.

Wrong

import { fhirDateTime } from "@northguild/gmt/regex";
fhirDateTime.test("2024-02-30");
// true — there is no 30 February

Right

import { isValidFHIR } from "@northguild/gmt/healthcare/validate";
isValidFHIR("2024-02-30", "dateTime");
// false
output 
MEDIUM

Refusing a leap second, or accepting it on any day

FHIR allows a second of 60, and the platform's date parser does not. A pattern that allows it accepts it on every day, though one was inserted only at the end of a few. isValidFHIR accepts only the inserted second itself (23:59:60 UTC, at any offset spelling), on a day one was inserted, and refuses a second of 60 anywhere else.

Wrong

new Date("2016-12-31T23:59:60Z").getTime();
// NaN — refused, though a second was inserted that day

Right

import { isValidFHIR } from "@northguild/gmt/healthcare/validate";
isValidFHIR("2016-12-31T23:59:60Z", "instant");
// true
isValidFHIR("2017-12-31T23:59:60Z", "instant");
// false
output 
MEDIUM

Comparing Z, +00:00 and -00:00 as strings

Z, +00:00 and -00:00 name the same offset. Compared as strings they are three offsets, and one instant reads as three. parseFHIR reads all three as +00:00 and keeps the spelling sent in value.

Wrong

"2024-06-15T10:30:00Z".slice(19) === "2024-06-15T10:30:00+00:00".slice(19);
// false — "Z" and "+00:00" are the same offset

Right

import { parseFHIR } from "@northguild/gmt/healthcare/parse";
parseFHIR("2024-06-15T10:30:00Z")?.offset === parseFHIR("2024-06-15T10:30:00+00:00")?.offset;
// true
parseFHIR("2024-06-15T10:30:00-00:00")?.offset;
// "+00:00"
output 
© 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.