T2.5: Creates Custom Schemas

Analysis Approach

Determining whether a custom HL7 schema is required involves carefully analyzing actual message samples and comparing them to the standard HL7 schema definitions. The HL7 version 2.x standard is intentionally flexible, allowing many optional segments and fields, so not every deviation from a strict interpretation requires a custom schema. Understanding when customization is truly necessary versus when standard schemas suffice is essential for efficient implementation.

When Custom Schemas Are Not Required

Custom schemas are not required in several common scenarios. If your messages simply omit optional segments that are defined in the standard but not always required, the standard schema handles this perfectly. For example, if an ADT_A01 message is missing the PD1 segment (which is optional in the standard), no custom schema is needed. Similarly, if messages include Z segments (custom segments starting with the letter Z) at the end of the message and you don't need to parse their contents, the standard schema accommodates them without customization.

When Custom Schemas Are Required

Custom schemas become necessary when messages deviate from the standard in ways that would cause parsing failures or validation errors. If a message is missing a segment that the standard defines as required, you need a custom schema that marks that segment as optional. If a standard segment contains additional fields beyond what the standard defines, or if field positions are different from the standard, a custom schema is required to properly parse those fields.

Other Customization Scenarios

Other scenarios requiring custom schemas include messages with segment structures that differ from the standard (segments in different order, segments repeating when they shouldn't, or segments not repeating when they should), messages using segments that don't exist in the HL7 standard (non-Z segments that are organization-specific), and messages where field datatypes or component structures differ from the standard. Careful analysis of actual message samples and comparison to standard schemas identifies these requirements.

Naming Conventions

Creating custom HL7 schemas in InterSystems HealthConnect begins with defining a new schema category with a unique name that clearly identifies it as a custom schema. Rather than using version numbers like "2.5" which are reserved for standard schemas, custom schemas use descriptive names like "HospitalXYZ_2.5", "Vendor_ADT_2.3.1", or "BE.SAP" (as shown in the PowerPoint examples). This naming convention makes it clear that these are customized schemas rather than standard HL7 versions.

Inheritance from Base Versions

Custom schemas are always based on an existing HL7 standard version. When creating a custom schema, you specify which standard version it extends - typically 2.3.1, 2.4, 2.5, or 2.7 depending on which version is closest to your actual message structure. This base version provides the foundation, and your custom schema only defines the deviations from that standard. This inheritance model means you don't have to redefine everything - only what differs.

Selective Redefinition

The power of this approach is that you redefine only message structures and segments that deviate from the standard. If your integration uses mostly standard ADT_A01 messages but has a custom ORU_R01 structure, you only need to define the custom ORU_R01 message structure in your schema. All other message types automatically use the standard definitions from the base version. Similarly, if most segments follow the standard but the PV1 segment has extra fields, you only redefine PV1.

Maintenance Benefits

This selective redefinition approach minimizes maintenance burden and reduces errors. When HL7 releases new versions or when you need to support additional standard message types, those work automatically through inheritance from the base version. You only maintain the specific customizations that your integration requires, making custom schemas much more manageable than they might initially appear.

Understanding Schema Notation

Understanding message structure notation in HL7 schemas is essential for reading schema definitions, creating custom schemas, and troubleshooting message validation issues. The InterSystems schema editor and documentation use specific visual conventions to indicate segment characteristics, and being able to interpret these conventions is a critical skill for the certification exam.

Required Segments

Required segments are displayed with a solid blue line (in the graphical schema editor) or marked as required in the text-based schema definition. The MSH segment is always required in every HL7 message - it's the message header and must be the first segment. Other segments may be required depending on the message type. For example, in ADT_A01, the EVN (event type) and PID (patient identification) segments are typically required. A message missing a required segment will fail validation.

Optional Segments

Optional segments are shown with a dotted green line or marked as optional in the schema definition. These segments may or may not appear in actual messages, and the schema allows both scenarios. For example, the SFT (software) segment is optional in many message types - if the sending system includes it, it's accepted and parsed, but if it's missing, validation still passes. The PD1 (additional patient demographics) segment is another commonly optional segment in ADT messages.

Repeating Segments

Repeating capability is indicated by parentheses notation after the segment name in the schema definition. For example, "SFT()" or "OBX()" indicates that zero or more occurrences of that segment can appear in the message. Some segments may be required but also repeating - for example, a message might require at least one OBX segment but allow multiple OBX segments to appear. The schema notation would show this as required (solid line) with parentheses for repeating.

Segment Groups

Segment groups are an important organizational concept in HL7 schemas. Groups are collections of related segments that are treated as a unit. Group names typically end with "grp" - for example, "PIDgrp" might contain the PID, PD1, and multiple NK1 segments related to patient demographics. Groups themselves can be optional or required, repeating or non-repeating. Nested groups (like "SACgrpgrp" shown in the PowerPoint) indicate hierarchical segment relationships where groups contain other groups.

Group Optionality Concept

Segment groups introduce an additional layer of complexity to HL7 message structure that is important to understand for schema design and message validation. A segment group can itself be optional, meaning the entire group of segments may or may not appear in a message. This is different from having individual optional segments - with an optional group, all segments in the group are treated as a unit regarding their presence or absence.

Interaction Between Group and Segment Requirements

The key concept to understand is the interaction between group optionality and individual segment requirements within the group. An optional group can contain segments that are marked as required within that group. This seems contradictory but makes sense when you understand the semantics: IF the group is present, THEN the required segments within it must be present. If the entire group is omitted, none of its segments appear, and that's valid.

Practical Example

For example, consider a "PIDgrp" that's optional but contains PID as a required segment and PD1 as an optional segment. A message can completely omit the PIDgrp - no PID, no PD1, and validation passes because the group is optional. However, if the message includes the PIDgrp (perhaps because it has a PD1 segment), then the PID segment must be present because it's required within that group. A message with PIDgrp containing only PD1 but missing PID would fail validation.

Nested Optionality

This nested optionality can extend to multiple levels with repeating groups and groups containing other groups. A message structure might have an optional repeating group containing required segments and optional subgroups. Understanding these relationships is essential for correctly defining custom schemas and predicting whether specific message samples will validate against a schema definition.

Overview of Repeating Groups

Repeating segment groups allow collections of related segments to appear multiple times within a single message, which is essential for representing complex healthcare data like multiple insurance coverages, multiple observation results, or multiple procedures. Each occurrence of a repeating group contains the same internal structure as defined in the schema, but the entire group can appear zero, one, or many times in the message.

Insurance Information Example

A classic example is insurance information in ADT messages. The IN1grp (insurance group) might contain IN1 (insurance), IN2 (insurance additional information), and IN3 (insurance additional information - certification) segments. This group is typically defined as repeating because patients often have multiple insurance coverages - primary, secondary, tertiary. Each insurance coverage gets its own occurrence of the IN1grp with its own set of IN1, IN2, and IN3 segments.

Laboratory Results Example

Laboratory results provide another common example. The OBXgrp in ORU messages might contain OBX (observation), NTE (notes and comments), and other related segments. This group repeats for each test result in the laboratory report. A comprehensive metabolic panel might have 14 OBXgrp occurrences, each with its own OBX segment for a specific test result and potentially its own NTE segments for result-specific comments.

Custom Schema Considerations

When defining custom schemas, correctly identifying which groups should repeat is critical for proper message parsing and validation. If the schema defines a group as non-repeating but actual messages contain multiple occurrences, validation will fail. Conversely, if a group is defined as repeating but should be singular, you might not catch validation errors in messages that incorrectly include multiple occurrences. Analyzing actual message samples helps identify the correct repeating characteristics for custom schema definition.

Inheritance Model

The inheritance model for custom schemas extends to message structure definitions, allowing you to selectively customize only those message types that deviate from the standard while automatically using standard definitions for everything else. This selective customization is a powerful feature that makes custom schemas practical to maintain in production environments.

Automatic Standard Support

When you create a custom schema based on HL7 version 2.5, for example, all standard 2.5 message structures are automatically available through inheritance. If your integration uses standard ADT_A01, ADT_A04, and ADT_A08 messages exactly as defined in the HL7 2.5 specification, you don't need to do anything - those message structures work automatically. You only need to define custom message structures for message types where your actual messages differ from the standard.

Focused Customization Example

For example, suppose your laboratory system sends ORU_R01 messages that include a custom Z segment in the middle of the message structure rather than at the end. You would define a custom ORU_R01 message structure in your schema that includes the Z segment in the correct position. All other message types - ADT_A01, ADT_A04, SIU_S12, etc. - continue to use their standard definitions from the base 2.5 schema. This focused customization minimizes the schema definition you need to maintain.

Evolution and Flexibility

This approach also provides flexibility for evolution. If you later need to support additional message types and they follow the standard, they work immediately without schema changes. If a new message type requires customization, you add just that one message structure definition to your custom schema. Over time, your custom schema grows to include only the specific customizations your integration requires, making it clear which message types have been customized and why.

Segment Inheritance

Just as message structure customization is selective, segment definition customization follows the same inheritance model. You only need to redefine segments that have different field structures, datatypes, or characteristics from the standard schema. All other segments automatically use their standard definitions from the base version, minimizing custom schema maintenance.

Common Reasons for Segment Redefinition

Common reasons for redefining segments include additional fields beyond the standard (for example, your ADT messages might include custom fields in PV1 after the standard fields), different field positions (perhaps field 5 in your messages corresponds to what would be field 6 in the standard), or different component structures within fields (maybe your patient name field has an additional component for a credential or title).

Redefining Segment Structure

When you redefine a segment in your custom schema, you provide a complete definition of that segment including all fields, their datatypes, optionality, and repeating characteristics. This redefined segment is then used whenever that segment type appears in messages processed with your custom schema. For example, if you redefine PV1 to include three custom Z fields at the end, every message type that uses PV1 (ADT_A01, ADT_A04, etc.) will use your custom PV1 definition.

Caution with Segment Customization

This segment-level customization is powerful but requires care. Because the custom segment definition applies everywhere that segment is used, make sure your customization is appropriate for all message types. If different message types use the same segment differently (which violates HL7 principles but sometimes occurs in practice), you may need to define multiple custom segment variants or work around the limitation in your transformation logic.

Field Definition Basics

When you create a custom segment definition, you provide detailed information about each field in the segment to enable proper parsing, validation, and field access in transformations and routing rules. Each field definition includes the field number (position in the segment), a descriptive name, the datatype (like ST for string, NM for numeric, TS for timestamp, or complex datatypes like XPN for extended person name), and optionality (required or optional).

Field Length Specifications

Field length specifications indicate maximum allowed length for the field, which is used for validation. If your custom segment has a patient account number field limited to 20 characters, the field definition would specify length=20, and messages with longer values in that field could be flagged during validation. Length is more strictly enforced for some datatypes than others - string fields often have length limits while numeric fields may not.

Repeating Fields

Repeating field capability must be specified in the field definition. If a field can contain multiple values (like multiple patient identifiers or multiple phone numbers), the definition indicates that the field repeats. This affects how the field is accessed in routing rules and DTL - repeating fields require occurrence notation like field(1) to access specific occurrences or special syntax to access all occurrences.

Code Tables for Coded Fields

For coded fields (fields that should contain values from a specific code set), you can reference code tables in the field definition. Code tables define valid values and their meanings, enabling validation that fields contain only acceptable codes. You can reference standard HL7 code tables or define custom code tables for organization-specific code sets. This code table association enables the schema to validate that coded fields contain appropriate values.