Skip to content

formatFHIR

  • 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.
formatFHIR(value: string, type: FhirDateType, options?: FhirFormatOptions): string

Write an ISO 8601 string as a FHIR R4 date, dateTime or instant: the inverse of parseFHIR.

  • FHIR R4 Datatypes §2.24.0.1 limits each type: date is YYYY, YYYY-MM or YYYY-MM-DD with no time zone; dateTime adds a time that SHALL carry seconds and a zone; instant is at least to the second and SHALL include a zone.

    TypePrecisions writtenDefault precision
    dateyear, month, daythe input’s, or day for an input with a time
    dateTimeyear, month, day, second, fractionthe input’s
    instantsecond, fractionthe input’s
  • It cuts and never rounds, so the result never names a later second, day or month than the input’s own wall clock. options.precision only lowers the precision; a finer one returns "".

  • Under date, the result is the wall-clock date at the input’s own offset (2024-06-15T23:30:00-05:00 is 2024-06-15), because §2.24.0.1 forbids a zone on a date.

  • The designator is written as the input spells it (Z, +00:00 and -00:00 stay as written; +05:30:00 is written +05:30). The fraction always uses ..

  • A second of 60 returns "": §2.24.0.1 says “applications producing them MAY choose to avoid encoding leap seconds”.

  • There is no hour or minute precision, and nothing is zero-filled: a value written to the hour or minute, with or without an offset, is written only when cut to a day or coarser (2024-06-15T23-05:00 is 2024-06-15 under date). An hour-only time is ISO 8601-1 §5.3.1.3 reduced precision, which Temporal reads.

  • An offset that is not a whole number of minutes returns "" (+02:00:30; Monrovia before 1972, Africa/Monrovia, was −0:44:30). This applies under date too, even though a date never writes the offset.

  • Disambiguation: none, in the vocabulary of LOCAL_TIME_RESOLUTION.md. A wall time with no offset is written only as a date. In a repeated hour at the end of DST, the offset decides which one is written.

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

  • Never throws: any failure, for input of any type, is "". The matching reader is parseFHIR.

ParameterTypeDescription
valuestringISO 8601 date, date-time, or date-time with an offset
typeFhirDateTypeThe FHIR type to write

options

How much of the value is written

Options for formatFHIR.

import type { FhirFormatOptions } from "@northguild/gmt";
OptionTypeDefaultDescription
precision?"year" | "month" | "day" | "second" | "fraction" (FhirPrecision)the input’s precision, or "day" under date for an input finer than a dayThe precision to write, no finer than the input’s.

the FHIR value, or "" when the value cannot be written as type

import { formatFHIR } from "@northguild/gmt/healthcare/format";
formatFHIR("2024-06-15T23:30:00-05:00", "date") // "2024-06-15"
output 

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