T1.3: Designs Custom Schemas

Overview

Understanding when custom schemas are required versus when standard schemas suffice is a critical skill for HL7 interface design. Custom schemas add complexity to your integration architecture, so they should only be created when genuinely necessary.

When Custom Schemas Are NOT Required

Missing Optional Segments

• HL7 schemas define many segments as optional (dotted lines or square brackets)
• Example: PD1 segment is optional in ADT_A01 messages
• If your sending system doesn't include optional segments, no custom schema needed
• The message validates successfully against the standard schema

Standard Z-Segments at End of Messages

• Thanks to the "-z" in default dm-z validation
• HL7 standard explicitly allows Z-segments at the end for vendor-specific extensions
• If you don't need to parse the fields within those segments, use standard schema
• The validation warning "Unrecognized Z Segment found after PV1" is informational, not an error

When Custom Schemas ARE Required

Scenario 1: Message Structure Deviations

• When required segments (like EVN in ADT_A01) are missing from messages you receive
• Create a custom schema that makes the segment optional for your environment
• Relaxes validation to match your actual message reality

Scenario 2: Extra Fields in Standard Segments

• When vendors add custom fields to segments (e.g., proprietary patient identifiers in PID)
• To parse these extra fields in DTLs, you must define them in a custom schema
• Without custom schema, you can't reference fields by name - only generic GetValueAt()

Scenario 3: Different Segment Structure

• When field order or cardinality differs from standard
• Some vendor implementations rearrange fields or change required/optional status
• Custom schemas document these variations and enable proper parsing

Scenario 4: Z-Segment Field-Level Parsing

• When you need to extract and process data from Z-segments in a DTL
• To reference ZEN.1 (encounter number) or ZPR.2 (provider NPI), fields must be defined
• Without custom schema, you can receive/forward but not parse Z-segment fields

Scenario 5: Non-Standard Segment Positions

• When custom segments appear in non-standard positions (e.g., between PID and PV1)
• Need custom schema to define where these segments belong

Decision Framework

• Use standard schemas: Messages conform to standard structure, don't need to parse custom fields
• Create custom schemas: Structure deviates from standard, or need to parse custom content
• Remember: Custom schemas add maintenance burden, so avoid when possible

Overview

Custom schemas in InterSystems HL7 implementation are organized using schema categories, which provide a powerful inheritance mechanism that minimizes the effort required to handle vendor-specific variations.

What is a Schema Category?

A container for a complete set of HL7 definitions:

• Message structures
• Segment definitions
• Data types
• Code tables

InterSystems IRIS for Health ships with standard schema categories: 2.3, 2.4, 2.5, 2.5.1, 2.6, 2.7, and 2.8.

Custom Category Naming

Good naming conventions include the base version and the source of variation:

• "2.5_Epic": Custom variation of HL7 2.5 for Epic systems
• "2.4_Cerner_Lab": Custom variation of HL7 2.4 for Cerner laboratory interfaces
• "2.5_LocalHospital": Local customizations for your hospital's specific needs

Inheritance Model

The power of custom schema categories:

• Custom "2.5_Epic" category inherits from standard "2.5" category
• Automatically includes all standard HL7 2.5 message structures, segments, data types, and tables
• You only define what differs from the standard
• Example: If Epic adds three custom fields to PID and includes a ZEN segment, you only define those variations

Maintenance Benefits

• Reduced effort: Only document deviations from standard
• Simplified upgrades: When moving from HL7 2.4 to 2.5, standard parts upgrade automatically
• Minimal schema definitions: Everything else comes from base category automatically

Schema Assignment

Custom schema categories are assigned to Business Services through Message Schema Category setting:

• When Business Service receives a message, it parses according to specified schema category
• Affects both validation (what's valid structure) and parsing (field accessibility in DTLs)

Namespace Scope

• Schema categories are namespace-scoped
• Custom schema created in one namespace isn't automatically available in others
• Need to recreate or export/import custom schemas in each namespace as needed

Multiple Coexisting Categories

Multiple custom schema categories can coexist in the same namespace:

• "2.5_Epic_Inpatient", "2.5_Epic_Ambulatory", "2.5_Cerner_Lab" - all in one namespace
• Each Business Service is assigned to one schema category
• Messages from different sources handled with appropriate schema variations

Multi-Level Hierarchies

• Inheritance supports multi-level hierarchies (rarely needed)
• Example: "2.5_Epic" based on "2.5", then "2.5_Epic_Cardiology" based on "2.5_Epic"
• Most organizations find one level of customization sufficient

Overview

Custom segment definitions are the heart of custom schemas, allowing you to document and parse vendor-specific extensions to HL7 messages. Understanding how to properly define custom segments is essential for handling real-world HL7 interfaces.

Z-Segment Naming Rules

The HL7 standard explicitly allows custom segments:

• Must have three-letter names
• First letter must be "Z"
• Common examples: ZEN (encounter), ZPR (provider), ZPV (visit), ZDX (diagnosis), ZIN (insurance)
• Standard restricts Z-segments to appearing at the end of messages

InterSystems Flexibility

Within a custom schema category:

• You can define Z-segments at any position in the message structure
• Not limited to the end of the message
• Essential when vendor systems place custom segments in non-standard positions
• Example: Some Epic implementations include ZPD between PID and PV1

Field-Level Definition

For each field in a custom segment, you specify:

• Field number: Position within the segment (1, 2, 3...)
• Field 0 is always the segment ID itself (like "ZEN")
• User-defined fields start at 1
• Field name: Descriptive identifier
• Example: "Encounter Number" or "Provider NPI"
• Becomes part of the property path in code or DTLs
• Data type: What kind of data the field contains
• Simple types: ST (string), NM (numeric), DT (date)
• Complex types: CX (extended composite ID), XPN (extended person name)
• Affects how field is parsed and how subcomponents are accessed
• Length: Maximum field length
• Informational and used for validation when stricter settings enabled
• Cardinality: Required/optional and repeating status
• [0..1]: Optional, non-repeating
• [1..1]: Required, non-repeating
• [0..n]: Optional, can repeat
• [1..n]: Required, can repeat
• Description: Documentation about the field's purpose

Accessing Custom Segment Fields

Once defined in your schema:

• Access fields in DTLs using dotted notation: source.ZEN.1 or target.ZEN.1
• Without custom schema, must use generic methods like GetValueAt("ZEN:1")
• Custom segments become first-class citizens in your integration environment

Practical Workflow

1. Receive sample messages from vendor 2. Identify Z-segments present 3. Document field structure (from vendor specs or reverse-engineering) 4. Create custom schema category 5. Define custom segments with field structures 6. Reference in routing rules, transform in DTLs, validate

Maintenance

• Vendor systems evolve, adding fields or changing data types
• Update custom schema definitions when vendor implementations change
• Good initial documentation helps future maintainers

Overview

The ability to read HL7 schema structure definitions and identify where actual messages deviate from those definitions is a critical skill for HL7 interface specialists. This skill is used during interface design, troubleshooting validation errors, and creating custom schemas.

Schema Notation Conventions

Text-Based Notation

• Square brackets [PD1]: Optional segment - may be present or absent
• No brackets (MSH, PID): Required segment - must be present
• Curly braces {ROL}: Repeating segment - zero, one, or multiple instances
• [{NK1}]: Optional and repeating

Numerical Notation

• [0..1]: Optional, non-repeating
• [1..1]: Required, non-repeating
• [0..n]: Optional, repeating
• [1..n]: Required, repeating

Graphical Diagrams

• Solid lines: Required segments
• Dotted lines: Optional segments
• Parentheses or special markers: Repeating segments

Example: ADT_A01 Structure (HL7 2.4)

• MSH: Required, unique (must appear exactly once)
• EVN: Required, unique (must appear exactly once)
• PID: Required, unique (must appear exactly once)
• [PD1]: Optional, unique (may appear zero or one time)
• [{ROL}]: Optional, repeating (may appear zero or more times)
• [{NK1}]: Optional, repeating (may appear zero or more times)
• PV1: Required, unique (must appear exactly once)
• [PV2]: Optional, unique (may appear zero or one time)

Analyzing Deviations

• Missing EVN: Deviation - required segment absent, dm-z validation error
• Two PV1 segments: Deviation - unique segment repeated, dm-z validation error
• Missing PD1: NOT a deviation - PD1 is optional
• Three NK1 segments: NOT a deviation - NK1 is repeating
• PV1 before PID: Deviation - segment order matters
• Z-segments at end: Allowed by dm-z validation
• Z-segments in middle: Flagged as errors

What dm-z Validation Checks

At the segment structural level:

• Are required segments present?
• Are unique segments not repeated?
• Is segment order correct?
• Are there unrecognized segments (except Z-segments at end)?

What dm-z Does NOT Check

Field-level validations:

• Are required fields within segments present?
• Do field values exceed maximum lengths?
• Do field values conform to code tables?
• Are data types correct?

Additional flags like "r" (required field) and "l" (length) are less commonly used.

Custom Schema Design Approach

• Goal: Make schema match actual messages you receive
• If vendor consistently sends messages without EVN, create custom schema where EVN is optional
• Allows messages to pass validation while enabling proper parsing

Key Skill

Given a message example and schema definition, identify:

• Which segments are missing that should be present
• Which segments are repeated that should be unique
• Which segments appear that aren't in the schema

Overview

Schema assignment is the mechanism that connects your message processing logic to the structural definitions that enable parsing and validation. Understanding where schemas are assigned, how they're used, and what capabilities they enable is fundamental to HL7 integration architecture.

Schema Assignment Location

Occurs at the Business Service level through the "Message Schema Category" setting:

• Specifies which schema category should be used to parse incoming messages
• Could be a standard category like "2.5" or a custom category like "2.5_Epic"
• Every message received by that Business Service will be parsed according to the specified schema category

Schema Assignment Purposes

1. Enables Message Parsing

• Raw HL7 message arrives as text with segments separated by carriage returns and fields by pipes
• Schema definition tells the system how to interpret that structure
• Identifies which segment is which, how many fields each segment has, what data types those fields use
• Transforms raw text into a structured object with properties that can be accessed by name

2. Provides Structure for Validation

• When message reaches a Business Process with validation enabled, the validation engine uses schema definition
• Without schema assignment, there's no basis for validation

3. Establishes DocType

• DocType format: "{SchemaCategory}:{MessageStructure}"
• Example: Business Service with "2.5" receives ADT_A01, DocType becomes "2.5:ADT_A01"
• Used throughout production for routing decisions, logging, and tracking

Without Proper Schema Assignment

• Validation cannot occur
• Field names cannot be used in routing rules or DTLs
• Must use generic field access methods like GetValueAt("PID:3.1")
• Routing rule constraints based on DocType won't work
• Essentially working with unparsed text instead of structured HL7 messages

Validation Sequence

1. Message received by Business Service 2. Schema category applied immediately to parse the message 3. Parsed message forwarded to target component (typically Business Process) 4. Validation occurs before routing rules execute (if enabled) 5. If validation fails, routing rules never run

Testing Service Consideration

A common source of confusion during interface testing:

• Testing Service allows manually submitting messages to components
• When bypassing Business Service, must manually specify DocType in testing interface
• Without DocType specification, validation fails and field-based routing rules won't work
• Most frequent testing mistake: copying message content but forgetting DocType field

Multiple Schema Assignments

For productions handling multiple HL7 versions or vendor variations:

• Different Business Services with different schema assignments
• Example: BS_Epic_ADT_TCP uses "2.5_Epic", BS_Cerner_Lab_TCP uses "2.4_Cerner_Lab"
• Each integration uses appropriate schema for parsing and validation

Troubleshooting with Schema Assignment

• Parsing errors: First check schema category assignment on Business Service
• Validation failures: Verify assigned schema category matches actual message structure
• Routing issues: Confirm DocType is being set correctly based on schema assignment