Healthcare mistakes
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.
HL7 version 2
Section titled “HL7 version 2”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 offsetconst 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 HelsinkiRight
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"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 sentRight
import { parseHL7 } from "@northguild/gmt/healthcare/parse";
parseHL7("1965");// { kind: "partial", local: "1965", offset: "", precision: "year" }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 dayRight
import { parseHL7 } from "@northguild/gmt/healthcare/parse";
parseHL7("20240615103000^D");// { kind: "partial", local: "2024-06-15", offset: "", precision: "day" }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 clearedRight
import { parseHL7 } from "@northguild/gmt/healthcare/parse";
parseHL7('""');// { kind: "null" }parseHL7("");// nullReading 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 JulyRight
import { parseHL7 } from "@northguild/gmt/healthcare/parse";
parseHL7("198807050000");// { kind: "local", local: "1988-07-05T00:00:00", precision: "minute" }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 goneRight
import { formatHL7 } from "@northguild/gmt/healthcare/format";
formatHL7("2024-06-15T10:30:45.98765-05:00");// "20240615103045.9876-0500"FHIR R4
Section titled “FHIR R4”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 sentnew Date("2024-06-15").toISOString();// "2024-06-15T00:00:00.000Z" — a time and a place nobody sentRight
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: "" }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 zonenew Date(value + "Z").toISOString();// "2024-06-15T10:30:00.000Z" — a place the resource never namedRight
import { parseFHIR } from "@northguild/gmt/healthcare/parse";import { isValidFHIR } from "@northguild/gmt/healthcare/validate";
parseFHIR("2024-06-15T10:30:00");// nullisValidFHIR("2024-06-15T10:30:00", "dateTime");// falseTreating 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 FebruaryRight
import { isValidFHIR } from "@northguild/gmt/healthcare/validate";
isValidFHIR("2024-02-30", "dateTime");// falseRefusing 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 dayRight
import { isValidFHIR } from "@northguild/gmt/healthcare/validate";
isValidFHIR("2016-12-31T23:59:60Z", "instant");// trueisValidFHIR("2017-12-31T23:59:60Z", "instant");// falseComparing 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 offsetRight
import { parseFHIR } from "@northguild/gmt/healthcare/parse";
parseFHIR("2024-06-15T10:30:00Z")?.offset === parseFHIR("2024-06-15T10:30:00+00:00")?.offset;// trueparseFHIR("2024-06-15T10:30:00-00:00")?.offset;// "+00:00"© 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.