RCD (Row Column Definition) is the three-component v2.4+ composite that describes one column in a tabular query response. Each RCD names a segment-field reference, declares the HL7 data type the column contains, and specifies a maximum column width in characters. A repeating RCD list in RDF-2 forms the schema for the rows that follow in RDT segments.
RCD was introduced in v2.4 alongside the tabular-response mechanism, which lets a query return a uniform table of rows rather than a heterogeneous mix of segments. The RDF+RDT pair is the v2 equivalent of a CSV header + rows, with RCD playing the role of the header row's column metadata.
Purpose
RCD exists to make tabular responses self-describing. Without it, an RDT row would be an undifferentiated list of |-separated values; with it, the receiver can know that column 3 is OBR-7 (Observation Date/Time), typed TS, with a maximum width of 26 characters — and parse the row accordingly. The schema-per-message design lets the sender adapt the table to the query without requiring a pre-shared definition.
The cost of that flexibility is that the receiver must implement a small dispatcher: read RDF-2 to build a column schema, then drive RDT parsing from that schema. Engines that hard-code an expected column order against a specific query template will break the first time the responder reorders or trims columns.
Component reference
Source: HAPI HL7v2 v2.8.1 javadocs — RCD. RCD has three components separated by ^.
| Seq | Name | Data Type | Length | Req | Description |
|---|---|---|---|---|---|
| RCD.1 | Segment Field Name | st | — | R | Fully-qualified segment-field reference (PID-5, OBR-7, OBX-5.1). Identifies the column's logical source. |
| RCD.2 | HL7 Data Type | id | — | R | HL70440 — the HL7 v2 data type code for the column's values (ST, NM, CWE, XPN, TS, CX, etc.). |
| RCD.3 | Maximum Column Width | nm | — | O | Maximum number of characters a value in this column may occupy. Receivers should size buffers and display columns accordingly. |
All three components are populated in practice; RCD.3 is technically optional but receivers that allocate fixed-width buffers depend on it.
Most-used components
- RCD.1 Segment Field Name — always populated; the column's source and de-facto column name.
- RCD.2 HL7 Data Type — always populated; drives value parsing.
- RCD.3 Maximum Column Width — populated except in streaming or display-agnostic profiles.
Where it's used
- RDF-2 Column Description — the canonical home. Each RDF segment carries a repeating RCD list (one per column) plus an RDF-1 column count. The RDT segments that follow encode one row each, with values positioned in the order the RCD list declares.
RCD is structurally a generic column descriptor and could in principle be reused elsewhere, but in published v2.8.1 RDF-2 is its only field.
Version differences
- v2.1 / v2.2 / v2.3 / v2.3.1 — No RCD. Tabular responses were not part of the standard; queries returned heterogeneous segment streams.
- v2.4 — RCD introduced alongside RDF/RDT. Three-component structure as published.
- v2.5 / v2.5.1 / v2.6 / v2.7 / v2.7.1 / v2.8 / v2.8.1 / v2.8.2 — Composition unchanged. HL70440 (HL7 Data Type) tracks the standard's expanding type catalog (e.g. CWE added v2.5, CNE added v2.5).
Common mistakes
- Out-of-vocabulary data type in RCD.2. RCD.2 is bound to HL70440. Custom or extension types must be agreed via a profile; receivers parsing against the published code system reject
MYTYPEorJSONoutright. - Column count mismatch. RDF-1 declares the column count; the number of RCD repetitions in RDF-2 and the number of values per RDT must match. Off-by-one bugs here corrupt every row.
- Empty RCD.1 with populated RCD.2/RCD.3. A column without a name is unparseable in practice — the receiver cannot bind it to a logical concept. Some engines accept positional-only columns, but cross-system portability requires RCD.1.
- Maximum width measured in fields rather than characters. RCD.3 is character count, not field count. Encoders that put
1here meaning "one field" trigger silent truncation at the receiver. - Declaring a composite type without populated sub-fields. If RCD.2 says
XPN, the receiver expects an XPN-shaped value in the row, including^-separated components. Senders that emit a flat name string break parsing.
Examples
Minimal column — patient name, max 60 chars:
PID-5^XPN^60
Numeric column — observation value:
OBX-5^NM^20
Coded column — observation identifier:
OBX-3^CWE^250
Timestamp column — observation date/time:
OBR-7^TS^26
In context — RDF segment carrying an RCD list (three-column patient roster):
MSH|^~&|EHR|MERCY|EMR|MERCY|20260624102000-0500||RTB^Q22^RTB_K13|MSG-RSP-44871|P|2.8.1
MSA|AA|MSG-QRY-44871
QAK|QID-44871|OK
QPD|Q22^Find Candidates^HL70471|QID-44871|@PID.3.1^MR884412
RDF|3|PID-3^CX^60~PID-5^XPN^60~PID-7^TS^26
RDT|MR884412^^^MERCY^MR|SMITH^JOHN^Q|19840712
RDT|MR000999^^^MERCY^MR|JONES^MARY^|19770305
Common pitfall — mismatched column count:
RDF|2|PID-3^CX^60~PID-5^XPN^60~PID-7^TS^26
RDT|MR884412^^^MERCY^MR|SMITH^JOHN^Q|19840712
RDF-1 declares 2 columns, RDF-2 has 3 RCDs, RDT has 3 values. The receiver either rejects the response (strict) or truncates to 2 columns (lenient), in which case the date-of-birth column silently disappears.
FHIR mapping
The v2-to-FHIR Implementation Guide does not publish a per-datatype ConceptMap for RCD. RCD describes tabular column structure; maps to Parameters.parameter or DataElement.definition depending on use case.
| HL7 v2 (RCD) | FHIR analog |
|---|---|
| RCD.1 Segment Field Name | Parameters.parameter.name or DataElement.definition.path |
| RCD.2 HL7 Data Type | Parameters.parameter.value[x] choice or ElementDefinition.type.code |
| RCD.3 Maximum Column Width | ElementDefinition.maxLength |
A complete RDF/RDT tabular response maps onto a FHIR Bundle of Parameters resources or, more idiomatically, a Bundle of typed resources (Patient, Observation) where each RDT row is reconstituted as one resource. The RCD-driven flat-table model has no first-class FHIR equivalent — FHIR's resource model expects typed structures, not generic rows.
Engine considerations
- Schema-driven parsing. Build an in-memory column schema from RDF-2 and parse RDT rows against it. Do not hard-code column order against a specific query — responders are free to omit or reorder columns based on the query.
- Type dispatch. RCD.2 governs which sub-parser to invoke for each column value. Wire a small table from HL70440 codes to type-specific parsers; an unknown HL70440 code should fail the entire response rather than guess.
- Width enforcement. RCD.3 is advisory at parse time but authoritative at emit time. Truncating an outbound value to RCD.3 chars is the sender's job; receivers that re-truncate corrupt data.
- HAPI accessors.
ca.uhn.hl7v2.model.v281.datatype.RCDexposesgetSegmentFieldName(),getHL7DataType(),getMaximumColumnWidth(). - Validation cross-checks. RDF-1 (column count) = repetitions of RCD in RDF-2 = values per RDT. Engines should validate the equality before parsing any row.
How Vorro parses and produces RCD
Vorro parses RDF-2 into an internal ColumnSchema(columns[]) where each Column carries (name, type, maxWidth). The schema is built once per response message and reused across every RDT row. RDT parsing is driven entirely from the schema — Vorro does not hard-code expected columns against any query template, so responders that add or remove columns work without code changes.
When producing RCD outbound, Vorro emits the column list in declaration order, with RCD.2 always populated from HL70440 (never a custom type) and RCD.3 sized from the maximum width Vorro observes across the rows it is about to emit. Outbound RDT values are truncated to RCD.3 chars with a logged warning rather than silently overflowing the declared width — this preserves the integrity of any downstream parser that pre-allocates buffers from the schema.
Related pages
- QIP data type — Query Input Parameter List (the request-side companion)
- RDF segment — Table Row Definition
- QSC data type — Query Selection Criteria
