HL7 RP Data Type: Reference Pointer

The RP (Reference Pointer) data type carries a URL, URI, or filename that points to a binary payload stored outside the HL7 message. It is the externalized counterpart to ED — used when the payload is too large to inline over MLLP, when the file already lives in a content repository, or when the receiver prefers to pull rather than be pushed. RP was introduced alongside ED in v2.3 and is used in OBX-5 when OBX-2 is RP.

Purpose

RP exists because inlining a binary payload as Base64 in ED breaks down at scale. A 20 MB DICOM object inflates to ~27 MB on the wire, exceeds typical MLLP receiver limits, and forces the engine to buffer the entire message before parsing. RP sidesteps the problem entirely: the message carries only a pointer (https://..., file://..., dicomweb://..., or a plain filename), and the receiver fetches the bytes out-of-band over HTTP, SMB, NFS, DICOM, or whatever protocol the pointer scheme implies.

Component table

Source: HAPI HL7v2 v2.8.1 javadocs (RP). Lengths are no longer published as fixed maxima in v2.8.1 (—). RP has 4 components.

Comp	Name	Sub-type	Length	Required	Description
RP.1	Pointer	st	—	R	URI, URL, or filename identifying the externally-stored payload.
RP.2	Application ID	hd	—	O	Application that hosts the payload — namespace ID, universal ID, universal ID type.
RP.3	Type of Data	id	—	R	[HL70191] AP, AU, FT, IM, NS, SD, TX — same table as ED.2.
RP.4	Subtype	id	—	R	[HL70291] PDF, JPEG, GIF, PNG, TIFF, BASIC, OCTET-STREAM, DICOM.

Most-used components

RP.1 Pointer — the URL, URI, or path. The most common production value is an https:// URL.
RP.3 Type of Data — broad MIME-style category mirroring ED.2.
RP.4 Subtype — specific format mirroring ED.3.
RP.2 Application ID — used when the receiver needs to know which content store to authenticate against.

Where it's used

RP appears in the same fields as ED, with the choice between them driven by payload size and the receiver's preference for push vs. pull:

OBX-5 Observation Value when OBX-2 Value Type is RP — the canonical home of out-of-band attachment references.
MFA-5, MFR-5 Master File Application-level Response — references to master-file payloads.
Custom Z-segments carrying URLs to scanned consent forms, ID images, large radiology PDFs, or DICOM studies.
DICOM workflow messages frequently use RP with dicomweb:// or wado:// schemes.

Version differences

v2.1 / v2.2 — RP did not exist. External references were carried as plain text in TX/FT.
v2.3 — RP introduced with the four components documented above. OBX-2 gains RP as a value-type code.
v2.4 – v2.6 — Subtype table HL70291 expanded to include PNG, DICOM, and OCTET-STREAM. Structure unchanged.
v2.7 – v2.8.1 — RP structure unchanged. Lengths removed from the standard; the practical limit on RP.1 is whatever the receiver's URL parser tolerates (typically 2048 chars for HTTP URLs).

Common mistakes

Sending an unreachable URL. RP only works if the receiver can resolve the pointer. Behind-the-firewall URLs (https://intranet.local/...) break for cross-organization integrations.
Embedding credentials in the URL. https://user:pass@host/... leaks credentials into logs and audit trails. Use scheme-appropriate auth (OAuth, mutual TLS, signed URLs) instead.
Mismatched type/subtype between RP.3/RP.4 and the actual payload. Declaring AP^PDF and serving an image/jpeg byte stream causes downstream viewers to misroute the file.
Forgetting that RP.1 may contain reserved characters. A URL containing & (query string) will tear the ED-style sub-component delimiter; HL7-escape it as T or URL-encode it as %26.
Stale or single-use pointers. Engines that retry messages can hit a 404 on the second attempt if the content store deleted the file after the first fetch. Pointers should be stable for the lifetime of the message's downstream replay window.

Examples

Minimal value — HTTPS URL to a PDF report

https://files.mercy.org/reports/r-9981.pdf^MERCY_FILES^AP^PDF

Pointer is a full HTTPS URL, Application ID is MERCY_FILES, type AP, subtype PDF.

Multi-component — DICOM study via WADO-RS

dicomweb://pacs.mercy.org/studies/1.2.840.113619.2.55.3.604688.123^MERCY_PACS^IM^DICOM

DICOMweb-style pointer; receiver resolves via WADO-RS.

In-context excerpt — OBX with out-of-band PDF

OBR|1|ORD-9981^MERCY|ACC-9981^MERCY|RPT^Radiology Report^L||||||||||||||||||F
OBX|1|RP|RPT^Radiology Report^L||https://files.mercy.org/reports/r-9981.pdf^MERCY_FILES^AP^PDF|||||F

OBX-2 is RP, OBX-5 is a four-component RP. The receiver fetches the bytes from files.mercy.org over HTTPS rather than decoding inline Base64.

Common pitfall — unescaped `&` in a query string

https://files.mercy.org/get?id=9981&type=pdf^MERCY_FILES^AP^PDF

The literal & in the query string is the HL7 sub-component separator. The parser will split RP.1 into https://files.mercy.org/get?id=9981 and type=pdf, corrupting the URL. Fix with URL encoding: ...?id=9981%26type=pdf or HL7 escape: ...Ttype=pdf.

FHIR mapping

The v2-to-FHIR Implementation Guide publishes ConceptMap-datatype-rp-to-attachment and ConceptMap-datatype-rp-to-documentreference. The pointer in RP.1 maps directly to Attachment.url, and the type/subtype pair collapses into Attachment.contentType.

RP component	FHIR element
RP.1 Pointer	`Attachment.url`
RP.2 Application ID	`DocumentReference.custodian` or `DocumentReference.author` (best-fit)
RP.3 Type of Data + RP.4 Subtype	`Attachment.contentType` (e.g. `application/pdf`)

Engine considerations

Reachability. Engines should validate at the integration design phase that the receiver can resolve every pointer scheme it might receive (https, file, dicomweb, etc.) and authenticate as needed.
Replay window. When a route supports retry-on-failure, the content store behind RP.1 must keep the file available for the full replay window (commonly 24–72 hours).
Credential handling. Inbound RPs containing embedded credentials should be sanitized before logging. Vorro's audit trail redacts the userinfo segment of any URL it sees.
Caching. Some engines pre-fetch the payload during message processing to surface 404s as message-level errors rather than silent downstream failures. Pre-fetch should be opt-in per route.
HAPI accessor. HAPI v2.8.1 exposes RP as ca.uhn.hl7v2.model.v281.datatype.RP with typed getters; RP.1 is a ST, RP.2 is an HD, RP.3 and RP.4 are ID.

How Vorro parses and produces RP

Vorro's HL7 parser reads RP into its canonical AttachmentReference model — pointer, hosting application, MIME-equivalent content type, all without dereferencing the URL during parse. Pre-fetch is an opt-in step on the route: when enabled, the engine pulls the bytes during processing, computes a SHA-256, and stores the payload in its attachment store so downstream consumers see a stable internal URL even if the upstream pointer later 404s.

On outbound, Vorro emits RP when a route's profile declares the field as RP, or as a fallback from ED when the inline payload would exceed the route's size ceiling. URLs are emitted with & characters HL7-escaped as T for v2 over MLLP. Application ID is populated from the attachment store's tenant configuration, and the type/subtype pair is derived from the stored MIME type via the same lookup table used for ED.

Sources

← Back to HL7 v2 Guide