Skip to content

parseHL7

  • 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.
parseHL7(value: string): Hl7DateTime | null

Read an HL7 v2 date-time (DTM, or the older TS) as what it states: a moment, the sender’s local time, or a span.

  • HL7 v2.5.1 2.A.22 (headed 2.A.1.22 in the hl7.eu v2.5.1 copy) defines the DTM YYYY[MM[DD[HH[MM[SS[.S[S[S[S]]]]]]]]][+/-ZZZZ]; 2.A.77 the TS, a DTM then ^ and a degree of precision.

    kindwhenmembers
    "instant"an offset and a minute or finerinstant, offset, local, precision
    "local"no offset and a minute or finerlocal, precision
    "partial"year, month, day or hourlocal, offset ("" when none), precision
    "null"the string ""none
  • No offset is the sender’s local time: 2.A.22, “if the time zone is not included, the time zone defaults to that of the local time zone of the sender”. It is never read as UTC; supply the sender’s zone to resolveLocal.

  • A partial value has no instant: padding a year or a day to a moment states a fact the sender did not send.

  • The degree of precision only lowers (2.A.77.2: it “may not indicate greater precision”), by cutting, never rounding. S on a fractional value cuts the fraction.

  • 0000 is the start of the stated day (2.A.22, 198807050000: “Midnight of the night extending from July 4 to July 5, 1988”), not the end of the day before.

  • +0000 and -0000 are both UTC (2.A.22), read as +00:00.

  • "" (two double quote marks) is the null value and differs from '' (ch. 2 §2.5.3: “is different from omitting an optional data field”); '' returns null.

  • A lone TS carries no MSH-2, so ^ separates its components, the separator Figure 2-1 recommends (ch. 2 §2.5.4). When a feed’s MSH-2 names another, the caller re-joins that TS with ^ first.

  • GMT reads TS.1 as exactly a DTM and TS.2 as exactly a Table 0529 code (or empty) and rejects anything else inside them, so 2024&X and 2024^D&X return null; that is GMT’s strict-kind rule, not an HL7 rule.

  • Components after TS.2 are present but not expected and are ignored (ch. 2 §2.6.2; a later version adds them at the end, §2.8.1 and §2.8.2), so 20240615^D^X reads as 20240615^D. An empty component is not present (§2.6.2), so 20240615^D^ reads as 20240615^D and ""^ as the null value, while ^D returns null. An ignored component still cannot hold |, ~ or a C0 control character (a carriage return ends the segment), so 20240615^D^X|Y returns null; a subcomponent (&), an escape sequence (\F\, §2.7) and white space are text and are ignored.

  • Second 60 and hour 24 are rejected, as is any day the month lacks.

  • Returns null on invalid input and for any value that is not a string. Never throws.

ParameterTypeDescription
valuestringHL7 v2 DTM or TS string

the reading, or null on invalid input

An HL7 v2 date-time (DTM, 2.A.22; or TS, 2.A.77) read as what it states. What the sender did not send is not invented: a value with no offset has no instant, and a year or a day has no moment.

import type { Hl7DateTime } from "@northguild/gmt";
type Hl7DateTime =
| {
/** An offset and a precision of a minute or finer: a moment in time. */
kind: "instant";
/**
* UTC, ISO 8601 ending in `Z`, as `toOffsetInstant` writes it (a sent fraction of `.1000`
* is `.1Z`; `local` keeps `.1000`).
*/
instant: string;
/** `±HH:MM`, as sent; `+0000` and `-0000` both read `+00:00`. */
offset: string;
/**
* The wall clock as sent, ISO 8601 extended, at the precision sent; seconds always written
* (`2024-06-15T10:30:00`, `2024-06-15T10:30:00.1234`).
*/
local: string;
/** The digits sent, or the `TS` degree of precision when it lowers them. */
precision: Hl7MomentPrecision;
}
| {
/** No offset and a precision of a minute or finer: the sender's local time. */
kind: "local";
/**
* The wall clock as sent, ISO 8601 extended, at the precision sent; seconds always written
* (`2024-06-15T10:30:00`, `2024-06-15T10:30:00.1234`). Ready for `resolveLocal` once you
* supply the sender's zone; HL7 2.A.22: "if the time zone is not included, the time zone
* defaults to that of the local time zone of the sender".
*/
local: string;
/** The digits sent, or the `TS` degree of precision when it lowers them. */
precision: Hl7MomentPrecision;
}
| {
/**
* Year, month, day or hour precision, with or without an offset: no single moment, so no
* instant.
*/
kind: "partial";
/**
* The wall clock as sent, ISO 8601 extended, at the precision sent: `2024`, `2024-06`,
* `2024-06-15`, `2024-06-15T10`.
*/
local: string;
/**
* `±HH:MM`, as sent; `+0000` and `-0000` both read `+00:00`; or `""` when the value
* carried none.
*/
offset: string;
/** The digits sent, or the `TS` degree of precision when it lowers them. */
precision: Hl7PartialPrecision;
}
| {
/**
* The HL7 null value `""` (two double quote marks), ch. 2 §2.5.3: "is different from
* omitting an optional data field". The old value "should be changed to null".
*/
kind: "null";
};
import { parseHL7 } from "@northguild/gmt/healthcare/parse";
parseHL7("20240615103000-0500") // { kind: "instant", instant: "2024-06-15T15:30:00Z", offset: "-05:00", local: "2024-06-15T10:30:00", precision: "second" }
output 

healthcare/parse/parseHL7.ts

© 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.