Proposal: Add HL7-style Path Accessor API (e.g., PID-3.1, PID-3[0].1.1)

[aarondglover]

Hi @davebronson

Thanks for the great work on ClearHL7 — it's been very useful.

I'm considering adding a feature to the project: an accessor/query API to retrieve HL7 values using HL7-style path syntax, such as:

• PID-3 → returns the full field (including all repetitions)
• PID-3.1 → returns the first component of the first repetition
• PID-3[0].1.1 → supports explicit repetition index (zero-based), component, and subcomponent navigation

The idea is to expose two methods like the following (probably implemented as a messagehelper)

string GetValue(string path);
T? GetValue<T>(string path); // returns null if parsing fails or not convertible

This would enable more dynamic readable access to fields without knowing the full C# classes.

Questions:

• Would this be a welcome addition to ClearHL7?
• Any suggestions or concerns around naming, syntax conventions, or extensibility?
• Is there an existing pattern in the library I should align with?

Happy to draft an implementation and open a PR if this aligns with the project direction.

Thanks,
Aaron

[aarondglover]

HL7 Path Accessor API Proposal

Adds safe, flexible access to HL7 message fields using HL7-style path strings.

---

Supported Path Format

SEGMENT-FIELD[REPETITION].COMPONENT.SUBCOMPONENT

• SEGMENT: 3-letter segment code (e.g., PID, OBX)
• FIELD: 1-based field index
• REPETITION: 0-based repetition index ([*] = all repetitions)
• COMPONENT / SUBCOMPONENT: 1-based, dot-separated

---

Public API

// Get a single scalar value (no wildcards allowed)
string GetValue(string path);
T? GetValue<T>(string path);

// Get multiple values (wildcards/repetitions supported)
IEnumerable<string> GetValues(string path);
IEnumerable<T?> GetValues<T>(string path);

---

Examples (Using PID-3: Patient Identifier List)

HL7 segment:

PID|1||12345^^^MRN^A~67890^^^NHS^A~ABC123^^^DR^A|

Path	Description	Result
PID-3	Full field as HL7-encoded string	"12345^^^MRN^A~67890^^^NHS^A~ABC123^^^DR^A"
PID-3[0]	First repetition	"12345^^^MRN^A"
PID-3[2].1	ID number in 3rd repetition	"ABC123"
PID-3[*].1	ID numbers from all repetitions	[ "12345", "67890", "ABC123" ]
GetValues<long>("PID-3[*].1")	Parsed as long (null on failure)	[12345, 67890, null]

---

Rules

• GetValue(...) does not support wildcards — use for scalar values only
• GetValues(...) supports repetition indexing and wildcards ([*])
• Generic overloads parse each value to type T; failures return null
• Missing components/subcomponents resolve to null or empty string ("")

---

Selectors and Ranges

This API also supports advanced ways to access repetitions within HL7 fields — like array slicing or filters.

Supported Selectors

Syntax	Description
PID-3[0]	Repetition at index 0 (first one)
PID-3[*]	All repetitions
PID-3[0:2]	Range: repetitions 0 through 2 (inclusive)
PID-3[1:]	Range: repetitions from index 1 to the end
PID-3[0,2]	List: only repetitions 0 and 2
PID-3[?4=="MRN"]	Filter: any repetition where component 4 equals "MRN"
PID-3[?!4=="MRN"]	Filter: NOT component 4 equals "MRN" (negation)

The number after the ? refers to the component number.

---

Patient Name Examples (Using PID-5)

HL7 segment:

PID|1||12345||Smith^John^A^^Mr.^MD~Jones^Alice^^Dr.|

Each repetition of PID-5 is a patient name (XPN).

Path	Description	Result
PID-5	Full field as HL7-encoded string	"Smith^John^A^^Mr.^MD~Jones^Alice^^Dr."
PID-5[0]	First name repetition	"Smith^John^A^^Mr.^MD"
PID-5[1].2	Given name from second name repetition	"Alice"
PID-5[*].1	Family names from all repetitions	[ "Smith", "Jones" ]
GetValues<string>("PID-5[*].1")	All family names (parsed)	[ "Smith", "Jones" ]

Patient names can repeat in some systems (e.g., aliases or alternate names), so repetition support is important.

---

Primitive & Complex Type Examples

HL7 segments often contain values that should be parsed into primitive types (like dates, numbers) or structured HL7 types (like XPN, CX).

Example HL7 Segment

PID|1||12345^^^MRN^A~67890^^^NHS^A||Smith^John^A^^Mr.^MD|19800101|M|||123 Main St^^Metropolis^NY^12345||555-1234|||M|123456789|987-65-4321||S||123456|

Primitive Type Examples

Path	Description	Method Call	Result
PID-7	Date of Birth (YYYYMMDD)	GetValue<DateTime>("PID-7")	1980-01-01
PID-3[0].1	Patient ID as number	GetValue<long>("PID-3[0].1")	12345
PID-13.1	Phone Number	GetValue<string>("PID-13.1")	"555-1234"

HL7 Complex Type Examples (using ClearHL7 types)

You can also retrieve full HL7 structured types like XPN (person name) or CX (composite ID).

Path	Description	Method Call	Result Type
PID-5[0]	First patient name (full XPN structure)	GetValue<XPN>("PID-5[0]")	XPN
PID-3[1]	Second identifier (full CX structure)	GetValue<CX>("PID-3[1]")	CX
PID-5[*]	All patient names	GetValues<XPN>("PID-5[*]")	IEnumerable<XPN>

For complex types, values are parsed using ClearHL7 segment/field models. You can access components like .FamilyName or .GivenName directly from the returned object.

---

[davebronson]

Nice work here, Aaron. Having a way to query a message for values is something I've considered before; it does sound useful.

My main suggestion is that we consider how other popular JSON, XML (et.al.) libraries structure their selectors so that ClearHL7's syntax is reasonably familiar. In looking at the examples above, it seems like you're already on the right path.