HL7 VH Data Type: Visiting Hours

The VH (Visiting Hours) data type is a small, four-component composite that publishes a recurring weekly time window: a starting day, an ending day, a starting hour, and an ending hour. It was introduced in HL7 v2.3 to give master-file and scheduling messages a single field that says "Monday through Friday, 08:00 to 17:00" without inventing a string convention per interface. Today it appears wherever an HL7 v2 message needs to advertise when a location, department, or resource accepts visitors, phone calls, or scheduled activity — most prominently inside the LOC, LCH, and LCC master-files segments and inside scheduling profiles that describe a resource's availability window.

Purpose

VH solves a narrow but recurring problem: every facility that exchanges location or resource master files has to communicate visiting hours, opening hours, or staffed hours, and free text is unparseable. Before VH, integrators stuffed the information into NTE notes or split it across several custom fields. VH gives the receiver four typed slots — two day codes from HL70267 and two TM hours — that an engine can read deterministically and convert into a calendar, a UI badge, or a FHIR Location.hoursOfOperation entry.

The composite is intentionally simple. It expresses a range of weekdays (start..end), not a list, so "Monday, Wednesday, Friday" requires three repetitions of the field rather than one VH. The hour range is a single open/close pair within those days; multi-shift schedules (e.g., morning and evening visiting blocks) also require repetition.

Component reference

Source: HAPI HL7v2 v2.8.1 javadocs — VH. VH has 4 components separated by ^.

The day range is interpreted as the closed interval from VH.1 through VH.2 in calendar order (MON < TUE < ... < SUN). A single-day window uses the same value in VH.1 and VH.2. The hour range is interpreted within local time at the location; VH does not carry a time-zone offset.

Most-used components

• VH.1 Start Day Range — anchors the window; almost always populated.
• VH.2 End Day Range — when omitted, many engines default to VH.1 (single-day window), but the spec does not require this; populate it.
• VH.3 Start Hour Range — the opening clock time. 0800 is more common in healthcare than 08:00:00; both are valid TM values.
• VH.4 End Hour Range — closing clock time. 2400 is not legal TM; use 2359 or send a second repetition spanning to the next morning.

Where it's used

VH is uncommon in transactional messages and common in master-file and scheduling traffic. Representative fields:

• LOC-11 Visiting Hours (Location master file)
• LCH-4 Location Characteristic Value when LCH-3 is a visiting-hours characteristic
• LCC-3 Visiting Hours on the Location Charge master segment
• AIS / AIG / AIL availability windows in some implementer profiles that repurpose VH for resource hours
• Custom Z-segments that publish phone-coverage hours for a clinic

It is not used for one-off appointment slots — those use DR (Date/Time Range) — and it is not used for staffed-hours-vary-by-week schedules, which require a richer scheduling model.

Version differences

• v2.3 — VH introduced with the same four components seen today.
• v2.3.1 / v2.4 — Day codes formalized against HL70267; no structural changes.
• v2.5 / v2.5.1 / v2.6 — No changes.
• v2.7 / v2.7.1 — Component data types refined (TM components carry the v2.7 TM precision rules).
• v2.8 / v2.8.1 / v2.8.2 — Structurally stable per HAPI v2.8.1 javadocs. 4 components, same names and order.

Common mistakes

• Sending a list of days in VH.1, like MON,WED,FRI. VH expresses a range; non-contiguous days require field repetition.
• Using locale day abbreviations (Mo, Lun, 1) instead of HL70267 codes. Receivers keyed off the table will drop or default the value.
• Putting 2400 in VH.4 to mean "midnight." 2400 is not a valid TM; use 2359 or roll the window into the next day with a second repetition.
• Omitting VH.4 because the location is "always open after VH.3." Engines mapping to Location.hoursOfOperation need both endpoints; absent close time, they cannot construct the FHIR closingTime and either reject or quietly drop the entry.
• Sending VH.3 / VH.4 as DTM values (20260101080000) instead of TM (0800). VH carries a recurring weekly time-of-day, not a wall-clock instant.

Examples

Weekday business hours — Monday through Friday, 08:00 to 17:00:

MON^FRI^0800^1700

Weekend afternoon visiting — Saturday and Sunday, 10:00 to 14:00:

SAT^SUN^1000^1400

Single-day window — Wednesdays only, 18:00 to 20:00:

WED^WED^1800^2000

24-hour window — Monday through Sunday, all day. Note the closing-time idiom:

MON^SUN^0000^2359

In context — LOC-11 Visiting Hours with two repetitions to express a split schedule (mornings weekdays, afternoons weekends):

LOC|1|WARD-3A^^^MercyHospital||W||MON^FRI^0800^1100~SAT^SUN^1300^1700

Common pitfall — list instead of range:

MON,WED,FRI^^0800^1700

The receiver sees MON,WED,FRI as a single unknown day code and either drops it or stores it verbatim.

FHIR mapping

There is no per-datatype ConceptMap published in the HL7 v2-to-FHIR Implementation Guide for VH. The mapping is implementation-level: VH translates directly into one entry inside Location.hoursOfOperation, with the day range expanded into the daysOfWeek repeating element.

The expansion is the awkward part. FHIR's daysOfWeek is a list of individual day codes (mon, tue, wed, ...), whereas VH compresses the same information into start..end. A mapping engine must expand MON^FRI into the five-element list [mon, tue, wed, thu, fri]. Going the other direction — FHIR to VH — only succeeds when the FHIR list is contiguous in calendar order.

Engine considerations

• Day expansion — engines should expand VH.1..VH.2 into an explicit weekday set as soon as the value lands, both to feed FHIR mappings and to normalize storage. Reversing the expansion on the way out is straightforward only when the set is contiguous.
• TM precision — VH.3 and VH.4 inherit TM's optional-precision rules. 08, 0800, 080000, and 08000000 are all legal TM values; engines should normalize to a single internal precision (typically HHMM).
• Repetition is the multi-window idiom — never embed multiple windows inside a single VH using non-standard separators. Use field-level ~ repetitions.
• Time-zone agnosticism — VH carries local wall-clock times. Engines crossing time-zone boundaries must attach the location's time zone from a sibling location field; VH itself never carries an offset.
• HAPI typing — ca.uhn.hl7v2.model.v281.datatype.VH exposes getStartDayRange(), getEndDayRange(), getStartHourRange(), and getEndHourRange(). Older-version VH classes share the same shape, so this is one of the rare composites where version differences rarely bite.

How Vorro parses and produces VH

Vorro treats VH as a tiny structured calendar fragment. On inbound:

• VH.1 and VH.2 are validated against HL70267; out-of-table values raise a soft warning and are passed through as opaque labels rather than dropped.
• The day range is expanded into an explicit weekday set the moment the field parses, so downstream FHIR mappers receive a daysOfWeek list with no further work.
• VH.3 and VH.4 are normalized to HHMM precision; a closing 2400 is rewritten to 2359 with a normalization note in the audit log.
• Multi-window schedules carried as field repetitions are aggregated into a single internal hours-of-operation record per location.

On outbound, Vorro emits one VH repetition per contiguous day block in the source schedule. A source schedule with five non-contiguous days produces five repetitions, never a comma-separated list inside VH.1.

Related pages

• TM data type — Time
• DR data type — Date/Time Range
• SPS data type — Specimen Source

Sources

• HAPI HL7v2 v2.8.1 javadoc — VH datatype
• HAPI HL7v2 v2.8.1 apidocs index
• HL7 v2 product brief