HL7 SAD Data Type: Street Address

The SAD (Street Address) data type was introduced in HL7 v2.5 as a sub-composite that lives inside XAD.1 — the Street Address Line of the Extended Address. SAD has just three components: a mailing-address line, a street name, and a dwelling number. The flagship use is breaking a free-form address line like 123 Main St Apt 4B into structured parts that downstream systems can index, format, and validate. Because SAD lives inside XAD.1, its components are separated by the sub-component delimiter & rather than by ^ — a subtle wire-format detail that trips up many engines.

Purpose

SAD exists because the first line of a postal address is the part most likely to be unparsed in legacy systems. Cities, states, zips, and countries have well-known column boundaries in any database; "123 Main St" does not. SAD adds structure: SAD.1 carries the mailing-address line as a whole (the value a postal sorter would print on a label), SAD.2 carries just the street name (for normalization against a street index), and SAD.3 carries the dwelling number (apartment, unit, suite). Receivers that need to validate against a USPS or postal database can use SAD.2 + SAD.3 as the structured key while still respecting SAD.1 as the human-readable line.

Components

Source: HAPI HL7v2 v2.8.1 javadoc (SAD). Length is not published in v2.8.1 javadocs (—).

Most-used components

• SAD.1 Street or Mailing Address — populated on essentially every address; the only universal way to be sure the receiver has some usable line.
• SAD.2 Street Name — populated when the sender has performed address normalization and can split out the street name.
• SAD.3 Dwelling Number — populated when there is a unit, apartment, or suite. Empty for single-family residences.

Where it's used

SAD does not appear as a standalone field on any segment. It is the sub-type of XAD.1 Street Address Line wherever an XAD is used:

• PID-11 Patient Address — patient's home/billing/mailing address.
• NK1-4 Next of Kin Address — emergency contact address.
• IN1-19 Insured's Address — policyholder address on insurance segments.
• GT1-5 Guarantor Address — guarantor billing address.
• ORC-23 Ordering Facility Address and OBX-24 Performing Organization Address — facility-level XAD fields.

In all of these the SAD components live nested inside the first XAD component, separated by &.

Version differences

• Pre-v2.5 — No SAD. XAD.1 was a plain ST holding the full address line as an unparsed string.
• v2.5 — SAD introduced as a 3-component sub-composite; XAD.1 retyped to SAD. The new structure is backwards-compatible at the SAD.1 position: senders that only populate SAD.1 produce a wire form indistinguishable from the legacy unparsed line.
• v2.6 / v2.7 / v2.8 / v2.8.1 — No structural changes; HAPI v2.8.1 javadoc shows the same 3 components.

Common mistakes

• Using ^ instead of & between SAD components. Because SAD lives inside a single XAD component (XAD.1), its parts must be separated at the sub-component level. Writing 123 Main St^Main^123 inside XAD.1 corrupts XAD by inserting two extra components.
• Putting the dwelling number in SAD.1 only. A line like 123 Main St Apt 4B in SAD.1 with SAD.2 and SAD.3 empty is valid but loses the parsing benefit — the receiver still has to regex the unit out.
• Putting the dwelling number in SAD.3 only and leaving SAD.1 empty. Pure-structured senders sometimes do this; a downstream label-printing system that reads only SAD.1 then prints a blank first line.
• Confusing SAD.3 Dwelling Number with the house/street number. In US locales, the leading number ("123") usually goes into SAD.1 as part of the mailing line; SAD.3 is for the unit, not the building.
• Sending non-address text in SAD. Senders sometimes overload SAD with care-of names, attention lines, or PO Box descriptors. Those belong in subsequent XAD components or in additional address-line repetitions, not in SAD.

Examples

Minimal value (single line only)

123 Main St

When SAD is used unparsed (SAD.2 and SAD.3 empty), the wire form is identical to a pre-v2.5 plain ST address line.

Structured value (all three SAD components)

123 Main St&Main&Apt 4B

Inside a single XAD.1 component, three SAD sub-components separated by &.

Inside a complete XAD field — PID-11 Patient Address

PID|1||MR-44119^^^MERCY&2.16.840.1.113883.19.5&ISO||Doe^Jane^A^^^^L||19850405|F|||123 Main St&Main&Apt 2B^Apt 2B^Anytown^CA^94000^USA^H

Verify positions inside the XAD:

PID-11 (XAD):
  123 Main St&Main&Apt 2B           XAD.1   Street Address Line (SAD)
    123 Main St                       SAD.1   Street or Mailing Address
    Main                              SAD.2   Street Name
    Apt 2B                            SAD.3   Dwelling Number
  Apt 2B                            XAD.2   Other Designation
  Anytown                           XAD.3   City
  CA                                XAD.4   State
  94000                             XAD.5   Zip
  USA                               XAD.6   Country
  H                                 XAD.7   Address Type

Note how & is the SAD delimiter inside XAD.1, while ^ is the XAD field-component delimiter.

Common pitfall — wrong delimiter

PID|1||MR-44119||Doe^Jane||19850405|F|||123 Main St^Main^Apt 2B^Anytown^CA^94000^USA^H

The sender used ^ to separate the SAD parts. The receiver now reads 123 Main St as XAD.1 (SAD), Main as XAD.2 (Other Designation), Apt 2B as XAD.3 (City), Anytown as XAD.4 (State), and so on — the whole address is shifted three components to the right.

Dwelling-only value

&&Apt 4B

A pathological but valid construction where only SAD.3 is populated. Most receivers will reject this because there is no mailing line; a sender producing it should also populate SAD.1 with the full string.

FHIR mapping

The v2-to-FHIR IG publishes SAD → Address. SAD components concatenate into Address.line[] entries, with SAD.1 typically becoming the first line and SAD.2 / SAD.3 split into additional Address.line entries when they are populated structurally.

In practice most v2-to-FHIR implementations collapse SAD.1 alone into Address.line[0] when SAD.2 and SAD.3 are empty; they only emit additional Address.line entries when the sender has produced a structured split.

Engine considerations

• Sub-component (&) parsing for SAD inside XAD: This is the headline pitfall. Engines that tokenize XAD at the ^ level only — without descending into XAD.1 at the & level — never see SAD.2 or SAD.3. A correct parser sees XAD.1 as an opaque string that must be further split on &.
• Round-tripping legacy unparsed lines: Pre-v2.5 senders emit only SAD.1. A v2.5+ engine must preserve that as 123 Main St with no & markers, not synthesize fake SAD.2/SAD.3 values. Round-tripping a plain line should produce a plain line.
• Encoding-character awareness: If a message redefines the sub-component delimiter (MSH-2 typically declares & as the fourth character), the engine must read the encoding-character set rather than hard-coding &. Internationalized messages occasionally use a non-default character set.
• Escaping literal &: Street names that contain a literal ampersand (e.g. Smith & Jones Way) must escape the character (T in standard HL7 escape sequences). Otherwise the receiver tokenizes mid-name.
• Repetition vs structure: A multi-line address (PO Box plus street) typically appears as repeated XAD field instances rather than as a single SAD with packed components.

How Vorro parses and produces SAD

On inbound, Vorro materializes SAD into Address.line[] of a FHIR Address. We descend into XAD.1 at the & level, populate line[0] from SAD.1, and emit line[1] / line[2] only when SAD.2 / SAD.3 carry values distinct from SAD.1. If the sender emitted only SAD.1, we never fabricate extra lines.

On outbound, Vorro respects the structure the upstream model carries: if the source Address.line[] is a single string, we emit it as SAD.1 with SAD.2 / SAD.3 empty (no & markers). If the source has structured street-vs-unit information, we emit all three SAD components separated by &. We always validate that the encoding-character set declared in MSH-2 includes & before serializing.

Related pages

• XAD data type — Extended Address
• XPN data type — Extended Person Name
• XCN data type — Extended Composite ID Number and Name for Persons

Sources

• HAPI HL7v2 v2.8.1 javadoc — SAD
• HAPI HL7v2 v2.8.1 apidocs index
• HL7 v2 product brief
• v2-to-FHIR ConceptMap — SAD to Address