The RDF (Table Row Definition) segment declares the shape of a tabular query response. It tells the receiver how many columns appear in each subsequent row and what data type, label, and width to expect for each column. Every RDT row that follows is interpreted against this definition.
Purpose
RDF announces the schema of an ad-hoc result set returned by a tabular query. A sending system uses RDF once, near the top of the response, and then emits one RDT segment per row. Without RDF the receiver has no way to know what each RDT column value means, which table or display label it carries, or how wide it is expected to be.
The segment is paired with RDT in display-oriented (DSR) and tabular (RTB) query responses, and it is conceptually similar to a column header row in a CSV or to a SELECT projection list in SQL.
Used in
RDF appears in tabular query response messages, primarily:
- DSR — Display Response, where rows are intended for human-readable rendering.
- RTB — Tabular Response, where rows are intended for machine processing.
Both flow inside the general query framework documented on QRY messages. RDF is typically preceded by a QAK/MSA acknowledgement and followed by one or more RDT segments.
Field-by-field reference
Source: HAPI HL7v2 v2.5.1 javadocs (https://hapifhir.github.io/hapi-hl7v2/v251/apidocs/ca/uhn/hl7v2/model/v251/segment/RDF.html) for sequence, name, data type, and repetition. Length is not published in the javadocs (—); Required and Table # are filled from the HL7 v2.5.1 standard where well-established.
| Seq | Name | Data Type | Length | Req | Repeat | Table # | Description |
|---|---|---|---|---|---|---|---|
| RDF-1 | Number of Columns per Row | nm | — | R | — | — | Count of columns in each RDT row. |
| RDF-2 | Column Description | rcd | — | R | Y | — | Repeating per-column name, data type, and width. |
Most-used fields
- RDF-1 Number of Columns per Row sets the expected arity of every RDT segment in the response.
- RDF-2 Column Description carries one repetition per column and supplies the column name (HL7 item label or free text), the data type the column value will use in RDT-1, and a maximum width hint for renderers.
Version differences (2.3 to 2.8.2)
- 2.3 introduced RDF/RDT as the row-definition / row-data pair for tabular and display query responses.
- 2.3.1 and 2.4 left the field set unchanged; RCD continued to be the data type for RDF-2.
- 2.5 and 2.5.1 retained the two-field structure verified in the HAPI v2.5.1 javadoc; no fields were added or deprecated.
- 2.6, 2.7, 2.7.1, 2.8, and 2.8.2 keep the segment intact for backward compatibility, although HL7 has steered new implementations toward the QBP/RSP query framework rather than DSR/RTB.
Common mistakes
- Sending more or fewer values in RDT than RDF-1 advertises. Receivers will either truncate or reject the row.
- Omitting an RDF-2 repetition for a column that is nonetheless populated in RDT. Each column must have a description.
- Reusing a single RDF for multiple unrelated result sets in the same message. Each tabular response should declare its own schema.
- Encoding column widths in RDF-2 that are smaller than the values actually returned, causing display truncation downstream.
Examples
Minimal RDF declaring two columns:
RDF|2|PatientID^ST^20~PatientName^XPN^48
Fully-populated RDF declaring four columns with explicit data types and widths:
RDF|4|PatientID^ST^20~PatientName^XPN^48~AdmitDate^TS^14~Service^IS^6
Annotated breakdown:
RDF Segment ID
|4 RDF-1 Number of Columns per Row
|PatientID^ST^20 RDF-2(1) Column 1: name, data type ST, width 20
~PatientName^XPN^48 RDF-2(2) Column 2: name, data type XPN, width 48
~AdmitDate^TS^14 RDF-2(3) Column 3: name, data type TS, width 14
~Service^IS^6 RDF-2(4) Column 4: name, data type IS, width 6
In-context excerpt — DSR tabular query response listing two patients:
MSH|^~&|LIS|MAIN|EHR|MAIN|20260610091500||DSR^Q03^DSR_Q03|MSG000341|P|2.5.1
MSA|AA|QRY000341
QAK|QRY000341|OK
RDF|3|PatientID^ST^20~PatientName^XPN^48~AdmitDate^TS^14
RDT|P10045^^^MAIN^MR~Doe^Jane^A~202606091200
RDT|P10046^^^MAIN^MR~Roe^Sam^B~202606091355
In-context excerpt — RTB tabular response returning a small charge list:
MSH|^~&|BILLING|MAIN|EHR|MAIN|20260610100200||RTB^Q13^RTB_Q13|MSG000342|P|2.5.1
MSA|AA|QRY000342
QAK|QRY000342|OK
RDF|2|ChargeCode^CE^20~Amount^MO^12
RDT|99213^Office Visit^CPT~125.00^USD
RDT|85025^CBC^CPT~24.50^USD
FHIR mapping
No segment-level ConceptMap is published in the v2-to-FHIR IG for RDF. Tabular query and update-subscription infrastructure has no direct FHIR resource equivalent; FHIR uses RESTful search (GET [base]/[Resource]?...) to project columns and Subscription for push updates. When migrating a DSR/RTB workflow to FHIR, model the column layout as the _elements parameter or a Bundle of resources rather than carrying it on the wire.
Engine considerations
- Most engines treat RDF as opaque metadata and pass it through unchanged, so any column rename or width change at the source propagates directly to downstream consumers.
- Validate that RDF-1 equals the number of RDF-2 repetitions before forwarding; mismatches surface as cryptic RDT parse errors later.
- Some engines reject a DSR/RTB message that contains RDT without a preceding RDF. Keep them in the same z-message group.
- When rewriting RDF-2 column names, ensure receivers that display headers are notified, since the change is silent from the protocol's point of view.
How Vorro parses and produces RDF
Vorro parses RDF by reading RDF-1 as the row arity and storing each RDF-2 repetition as a structured column descriptor (name, data type, width). The descriptor is attached to the parsed message context so downstream RDT segments can be projected into typed columns automatically. Producing RDF inverts the process: Vorro derives the column list from the channel's response schema, counts it into RDF-1, and emits one RCD repetition in RDF-2 per column, preserving the order used by the RDT generator.
