Handle non-standard Z-segments and repeating-field quirks when mapping HL7v2 messages to FHIR resources

Steps

1. Inventory every Z-segment and locally extended or repeating field present in real trading-partner traffic before mapping — Z-segments are explicitly outside HL7's published standard v2-to-FHIR Segment Maps.
2. For each Z-segment, decide per HL7 v2-to-FHIR IG guidance whether to represent it as a FHIR extension or intentionally drop it, based on downstream clinical/business value.
3. Scope any Z-segment extension URI to your own organization/system rather than to the Z-segment's name, since identically named Z-segments can carry different meanings across sending systems.
4. For standard segments with local repeating-field/component quirks (e.g., extra repetitions appended to PID-3 or NK1), write defensive parsing that iterates all repetitions instead of assuming fixed cardinality.
5. Search the FHIR extension registry and existing HL7 v2-to-FHIR ConceptMaps before defining a new local extension, and escalate to the relevant HL7 work group for common unmet needs.
6. Maintain a migration plan for local Z-segment extensions in case HL7 later standardizes an equivalent mapping.