The AD (Address) data type is the original flat postal-address structure that shipped with HL7 v2.1 and was superseded by XAD in v2.3. It carries eight flat ST/ID components - street, other designation, city, state, postal code, country, address type, and other geographic designation - with no effective/expiration dates and no structured street sub-type. AD is retained in the v2.8.1 standard for backward compatibility and still appears in pre-v2.3 messages and a small number of custom Z-fields, but new messages should use XAD.
Purpose
AD exists to exchange a postal address in a single flat repetition. Unlike XAD it has no validity period, no county/census tract, and no structured Street Address sub-type, so a sender cannot distinguish a current home address from a prior one within the same field - repetitions are the only mechanism, and the address-type code in AD.7 is the only discriminator. Modern integrations encounter AD primarily when interfacing with legacy lab, ADT, or master-file systems that have never been upgraded past v2.2, or in custom Z-segments that froze their schema before XAD existed.
Component table
Source: HAPI HL7v2 v2.8.1 javadocs (AD). Lengths are no longer published as fixed maxima in v2.8.1 (-). AD has 8 components.
| Comp | Name | Sub-type | Length | Required | Description |
|---|---|---|---|---|---|
| AD.1 | Street Address | st | - | O | Flat street line (no SAD sub-structure). |
| AD.2 | Other Designation | st | - | O | Apt / suite / unit / building / floor. |
| AD.3 | City | st | - | O | City or locality. |
| AD.4 | State or Province | st | - | O | State, province, or sub-national region. |
| AD.5 | Zip or Postal Code | st | - | O | ZIP or postal code, country-specific format. |
| AD.6 | Country | id | - | O | [HL70399] ISO 3166-1 alpha-3 country code. |
| AD.7 | Address Type | id | - | O | [HL70190] H home, M mailing, B billing, O office, etc. |
| AD.8 | Other Geographic Designation | st | - | O | Region, district, locality not fitting state/city. |
Most-used components
- AD.1 Street Address - flat street line; no dwelling/street-name split.
- AD.3 City - locality.
- AD.4 State or Province - USPS 2-letter for US senders; free text elsewhere.
- AD.5 Zip or Postal Code - ZIP+4 or country-specific postal code.
- AD.6 Country - ISO 3166-1 alpha-3 from HL70399.
- AD.7 Address Type (HL70190) -
Hhome,Mmailing,Bbilling,Ooffice.
Where it's used
AD is no longer the canonical address carrier in the v2.8.1 base standard - XAD has replaced it in every field that previously used AD. Legacy occurrences include:
- Pre-v2.3 PID-11 Patient Address - flat AD repetitions.
- Pre-v2.3 NK1-4 Next of Kin Address.
- Pre-v2.3 GT1-5 Guarantor Address and IN1-19 Insured's Address.
- Custom Z-segments that froze their schema at v2.2 (e.g.
ZIN-7 Insured Addressas AD). - Site-specific master-file extracts that retained AD for backward compatibility with downstream loaders.
Version differences
- v2.1 / v2.2 - AD introduced with the eight flat components documented above. Used by every address-bearing field in the standard.
- v2.3 - XAD introduced as the structured replacement. Every base-standard field that carried AD was migrated to XAD. AD is retained in the data-type catalogue but flagged as legacy.
- v2.4 – v2.8.1 - AD structure unchanged. The standard continues to publish AD for backward compatibility but new fields never use it. In new messages, use XAD.
Common mistakes
- Emitting AD on a v2.3+ field that expects XAD. Receivers parsing PID-11 as XAD will misalign components - AD.7 Address Type lands where XAD.7 expects it, but AD.8 collides with XAD.8 and there is no place for effective/expiration dates.
- Treating AD.1 as if it were a SAD composite. AD.1 is plain ST;
123&Main&Stwill be received verbatim as a single string with literal&characters, not parsed into sub-components. - Local country abbreviations instead of ISO 3166 alpha-3. Sending
USorUnited Statesin AD.6 breaks downstream systems expecting HL70399 (USA). - Free-text state names. US profiles expect the USPS 2-letter abbreviation in AD.4.
- Assuming AD carries an effective period. It does not - there is no equivalent of XAD.13 / XAD.14. If you need address history, you need XAD.
Examples
Minimal value
123 Main St^^Anytown^CA^94000
Fully populated AD with all eight components
123 Main St^Apt 4B^Anytown^CA^94105-1234^USA^H^San Francisco County
123 Main St street, Apt 4B other designation, Anytown city, CA state, 94105-1234 ZIP+4, USA country, H home address type, San Francisco County other geographic designation.
Legacy sender still emitting AD on a custom Z-field
ZIN|1|MEMBER123||123 Main St^Apt 4B^Anytown^CA^94105^USA^H
A pre-v2.3 insured-info Z-segment that never migrated to XAD. The parser must know ZIN-4 is AD, not XAD.
In-context excerpt - pre-v2.3 PID-11
PID|1||MR884412^^^MERCY^MR||Smith^John^Q||19720508|F|||123 Main St^Apt 4B^Anytown^CA^94105^USA^H
Identical to a single-repetition XAD on the wire, but the schema for the field is AD - there are no components beyond AD.8.
Common pitfall - AD sent on a v2.8.1 PID-11
PID|1||MR884412^^^MERCY^MR||Smith^John^Q||19720508|F|||123 Main St^Apt 4B^Anytown^CA^94105^USA^H^Other Geo
If the receiver parses PID-11 as XAD (correct for v2.8.1), Other Geo lands in XAD.8 fine, but there is no XAD.13 / XAD.14, and any downstream "current vs. historical" logic that expects effective dates silently sees nulls.
FHIR mapping
There is no v2-to-FHIR Implementation Guide ConceptMap published specifically for AD - the IG covers XAD instead. AD maps to FHIR Address using the same component-to-element correspondence as XAD for components .1 through .8.
| AD component | FHIR element |
|---|---|
| AD.1 Street Address + AD.2 Other Designation | Address.line (multiple entries, one per line) |
| AD.3 City | Address.city |
| AD.4 State or Province | Address.state |
| AD.5 Zip or Postal Code | Address.postalCode |
| AD.6 Country | Address.country |
| AD.7 Address Type | Address.use (home/work/temp/old) and Address.type (postal/physical/both) |
| AD.8 Other Geographic Designation | Address.district (best-fit) |
Engine considerations
- Schema detection. Engines must know whether a given field is typed AD or XAD based on the message version and segment field definition. Parsing AD as XAD or vice-versa works for the first eight components but breaks the moment XAD.9+ is populated.
- No effective dates. AD cannot carry validity periods. If a downstream system needs current-vs-historical filtering, upgrade the field to XAD or store the period out-of-band.
- No SAD sub-structure. AD.1 is plain ST. Engines that present a structured "dwelling number / street name / street type" UI for XAD should fall back to a single-line input for AD.
- Legacy-handling guidance. Inbound AD should be lifted into the engine's canonical address model as if it were a single-repetition XAD with only .1–.8 populated; outbound serialization must respect the wire schema and emit AD (not XAD) when the receiver's profile is pre-v2.3.
- HAPI accessor. HAPI v2.8.1 exposes AD as
ca.uhn.hl7v2.model.v281.datatype.AD; it is still generated for backward compatibility but rarely referenced by base-standard segment getters.
How Vorro parses and produces AD
Vorro's HL7 parser treats AD as a degenerate single-repetition variant of its canonical PostalAddress model: components .1 through .8 populate the same fields they would on XAD, with effective/expiration dates left null and the structured SAD sub-type collapsed to a flat street string. The parser detects AD by consulting the segment-field schema for the message version, not by inspecting the value on the wire, so an AD-typed field that happens to contain extra ^ separators is rejected rather than silently re-typed.
On outbound, Vorro emits XAD by default. AD is only produced when a downstream profile explicitly declares the field as AD (typically a pre-v2.3 receiver or a custom Z-segment), in which case the engine drops XAD.9–XAD.14 and emits only the eight AD components. Country is always emitted as ISO 3166-1 alpha-3 and state as USPS 2-letter for US addresses, matching the XAD conventions.
