# Healthcare

Industry: Healthcare

Healthcare is time in clinical messages. HL7 International calls version two of its HL7 messaging standard "one of the most widely implemented standards for healthcare information in the world". A date and time in an HL7 message says how precise it is by how many digits it carries, and leaves the place out unless the sender adds an offset. A FHIR date follows the ISO date format but can stop at a year or a month, and a FHIR time must carry a zone. This layer reads and writes both without guessing the place.

## What these functions solve

- **A message time with no offset is stored as UTC.** [`parseHL7`](/gmt/reference/healthcare/parse/parseHL7/) returns it as a local time with no instant, so the sending facility's zone has to be named before it becomes one. See [guide](/gmt/guides/industries/healthcare-clinical-timestamps/), [scenario](/gmt/scenarios/an-hl7-time-read-as-utc/), [HL7 Timestamp Reader](/gmt/tools/hl7-timestamp-reader/).
- **A birth year is padded to midnight on the first of January.** [`parseHL7`](/gmt/reference/healthcare/parse/parseHL7/) keeps a year, month, day or hour as a partial value with its precision and no instant, and [`parseFHIR`](/gmt/reference/healthcare/parse/parseFHIR/) does the same for a FHIR year, month or day. See [scenario](/gmt/scenarios/a-fhir-month-padded-to-midnight/), [HL7 Timestamp Reader](/gmt/tools/hl7-timestamp-reader/), [FHIR Date Checker](/gmt/tools/fhir-date-checker/), [guide](/gmt/guides/industries/healthcare-clinical-timestamps/).
- **An older time stamp whose precision code says it is a date is read as a time.** [`parseHL7`](/gmt/reference/healthcare/parse/parseHL7/) reads the precision code and cuts the value to it, never past the digits sent. See [scenario](/gmt/scenarios/a-ts-date-read-as-a-time/).
- **A message clears a stored time by sending the null value, and the reader drops it as empty.** [`isValidHL7`](/gmt/reference/healthcare/validate/isValidHL7/) accepts the null value and [`parseHL7`](/gmt/reference/healthcare/parse/parseHL7/) returns it as its own kind, so it is never mistaken for a missing field. See [guide](/gmt/guides/industries/healthcare-clinical-timestamps/).
- **An instant is written back with its offset lost or rounded.** [`formatHL7`](/gmt/reference/healthcare/format/formatHL7/) writes the offset the value has, cuts to the precision asked for and never rounds. See [guide](/gmt/guides/industries/healthcare-clinical-timestamps/).

Start with the guide: [Healthcare: Clinical Timestamps](/gmt/guides/industries/healthcare-clinical-timestamps/).

## Its own functions

### [`healthcare`](/gmt/reference/healthcare/)

**[format](/gmt/reference/healthcare/format/)**

- [`formatFHIR`](/gmt/reference/healthcare/format/formatFHIR/): Write an ISO 8601 string as a FHIR R4 `date`, `dateTime` or `instant`: the inverse of `parseFHIR`.
- [`formatHL7`](/gmt/reference/healthcare/format/formatHL7/): Write an ISO 8601 string as an HL7 v2 date-time (`DTM`): the inverse of `parseHL7`.

**[parse](/gmt/reference/healthcare/parse/)**

- [`parseFHIR`](/gmt/reference/healthcare/parse/parseFHIR/): Reads a FHIR R4 `date`, `dateTime` or `instant` string (R4 Datatypes §2.24.0.1) as it is written, and returns what it states: the input, its precision and its offset.
- [`parseHL7`](/gmt/reference/healthcare/parse/parseHL7/): 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.

**[validate](/gmt/reference/healthcare/validate/)**

- [`isValidFHIR`](/gmt/reference/healthcare/validate/isValidFHIR/): Return true when `value` is a real FHIR R4 `date`, `dateTime` or `instant`, as `type` names.
- [`isValidHL7`](/gmt/reference/healthcare/validate/isValidHL7/): Return true when `value` is an HL7 v2 `DTM`, or a `TS` with a degree of precision the digits carry, that `parseHL7` reads.

## Guides

- [Healthcare: Clinical Timestamps](/gmt/guides/industries/healthcare-clinical-timestamps/): Read and write the date-times in HL7 version 2 messages and FHIR R4 resources, keep an HL7 time with no offset local until you name the sender's zone, require a zone on a FHIR time, and keep a partial date a span.

## Tools

- [FHIR Date Checker](/gmt/tools/fhir-date-checker/): Type a FHIR R4 date, dateTime or instant. The tool says which of the three types the value fits, what it names, and what formatFHIR writes back, and it keeps the precision that was sent.
- [HL7 Timestamp Reader](/gmt/tools/hl7-timestamp-reader/): Type an HL7 v2 date-time. parseHL7 says whether it states an instant, an offset, a local time or only a partial date, and the tool reads a value with no offset in the zones you choose and shows what formatHL7 writes back at each precision.

## Scenarios

- [A FHIR Month Padded to Midnight](/gmt/scenarios/a-fhir-month-padded-to-midnight/): A FHIR date sent as a month, turned into a midnight instant, so a range check counts the whole month as its first moment.
- [A TS Date Read as a Time](/gmt/scenarios/a-ts-date-read-as-a-time/): An older HL7 time stamp whose degree of precision says month, read as noon on the first of April.
- [An HL7 Time Read as UTC](/gmt/scenarios/an-hl7-time-read-as-utc/): A lab observation time sent as an HL7 date-time with no offset, stored as a UTC instant the message never stated.

## Mistakes

- [Healthcare](/gmt/mistakes/healthcare/): Common mistakes with HL7 version 2 and FHIR R4 dates and times, from an offset that is not there to a month padded to midnight, in GMT's healthcare layer.
