Skip to content

formatHL7

  • 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.
formatHL7(value: string, options?: Hl7FormatOptions): string

Write an ISO 8601 string as an HL7 v2 date-time (DTM): the inverse of parseHL7.

  • 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] and says “the number of characters populated (excluding the time zone specification) specifies the precision”.

    Input formWritten precisionExample result
    2024year2024
    2024-06month202406
    2024-06-15day20240615
    2024-06-15T10hour2024061510
    2024-06-15T10:30 / …:00 / …:00.fminute / second / fraction202406151030 / 20240615103000 / 20240615103000.f
    the same with Z or ±HH:MMas written, then ±HHMM20240615103000-0500
  • The precision is read from the form the input is written in; options.precision only lowers it, and a finer one returns "". A value is cut to its precision and never rounded, so the result never names a later minute, hour or day than the input. A fraction is cut to four digits, the most 2.A.22 allows.

  • It never writes TS: v2.6 2.A.77 says it was “withdrawn and removed from the standard as of v 2.6”, so the result never holds ^.

  • A value with no offset writes none, and the HL7 value then means 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”). To send a facility’s wall clock with its offset, pass that wall clock written with the zone’s offset (2024-06-15T10:30:00-05:00).

  • The offset written is the one the value carries; Z writes +0000. It is never dropped and never rounded: an offset that is not a whole number of minutes returns "".

  • Z and -00:00 (RFC 9557 §2.2: UTC known, local offset unknown) write +0000; HL7 has no spelling for an unknown offset (2.A.22: “+0000 or -0000 both represent UTC”).

  • A date with an offset is not ISO 8601 and returns "". An hour with one is ISO 8601-1 §5.3.1.3 reduced precision and is written (2024-06-15T10-05:00 is 2024061510-0500). To write a date with its offset, pass the instant with precision: formatHL7("2024-06-15T10:30:00-05:00", { precision: "day" }) is 20240615-0500.

  • Disambiguation: none. The function never converts a wall time without an offset to an instant.

  • Annotations: none is read. A bracket of any kind (a zone, [u-ca=iso8601], [foo=bar]) returns ""; write the wall clock with the zone’s offset instead.

  • A minute-precision local from parseHL7 reads back with :00 seconds; to write the same digits, pass { precision: result.precision }.

  • A year outside 0000–9999 returns "".

  • Never throws: any failure, for input of any type, is "".

ParameterTypeDescription
valuestringISO 8601 date, date-time, or date-time with an offset

options

How much of the value is written

Options for formatHL7.

import type { Hl7FormatOptions } from "@northguild/gmt";
OptionTypeDefaultDescription
precision?Hl7PartialPrecision | Hl7MomentPrecision (Hl7Precision)the precision of the inputLowers the precision written; never raises it. The precision is read from the form the input is written in, and a value lower than that cuts the digits (never rounds).

the DTM, or "" when the value cannot be written

The precision of an HL7 v2 date-time, coarsest first. HL7 v2.5.1 ch. 2A 2.A.22 (headed 2.A.1.22 in the hl7.eu v2.5.1 copy): “The number of characters populated (excluding the time zone specification) specifies the precision”. The characters before the offset, per member:

import type { Hl7Precision } from "@northguild/gmt";
Hl7PartialPrecision | Hl7MomentPrecision
import { formatHL7 } from "@northguild/gmt/healthcare/format";
formatHL7("2024-06-15T10:30:00-05:00") // "20240615103000-0500"
output 

healthcare/format/formatHL7.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.