HL7Spy Schema Editor - Enterprise Only
1. Overview
The HL7Spy Schema Editor is a comprehensive tool for managing HL7 message schemas, allowing users to create, modify, import, and export HL7 segment, field, and code table definitions. This editor provides an intuitive interface for working with HL7 standards and custom schema modifications.
The video below shows how to import a segment definition from an existing specification.
After importing the specification, the field definitions appear in HL7Spy as shown below.
2. Getting Started
2.1 Opening the Schema Editor
From Main Application: Navigate to the File Ribbon Tab and select the “HL7 2.x Schemas” button to bring up the Schema Editor
Popup Schema Editor: Click the button under the HL7 Schema version in focused editing sessions
2.1 Schema Information Tab
3.1 Schema Information Fields
This section references numbered elements [1] through [11] that correspond to specific UI components in the Schema Information interface. Each numbered element is documented below with its exact location and functionality.
1. Version Dropdown [1]
Purpose: Choose the HL7 version that will be used as the base schema that will be used by the editor for selecting values from.
2. Save Button [2]
Purpose: Save the contents of the configured schema to disk
Shortcut: Ctrl+S
3. Revert Button [3]
Purpose: Revert any changes you have made since the last save
4. Short Name Field [4]
Purpose: A unique identifier for the schema package. Must be 4-20 characters long and follow specific naming conventions.
Validation Rule: Must match pattern .{4,20} (4 to 20 characters)
Example: "HL72UK.A3"
5. Package ID Field [5]
Purpose: Automatically generated unique identifier for the package. This field is read-only and is created by combining the Organization and Short Name fields.
Auto-Generated: Format: {Organization}.{ShortName} (sanitized for NuGet compatibility)
Example: "HL7Spy.HL72UK.A3"
6. Version Field [6]
Purpose: Version number of the schema package. Must follow semantic versioning with HL7 compatibility indicator.
Validation Rule: Must match pattern 1\\.\\d{1,2}\\.\\d{1,3} (e.g., 1.2.3)
Requirements:
Must start with "1" to denote HL7 Version compatibility
Version is automatically updated whenever the HL7 Schema is modified
Example: "1.0.31"
7. Last Modified Field [7]
Purpose: Timestamp indicating when the schema was last modified. This field is automatically managed by the system.
Read-only: This field is automatically updated by the system and cannot be manually edited.
Example: "9/4/2025 9:51:12 PM -07:00"
8. Organization Field [8]
Purpose: Name of the organization or entity responsible for the schema package.
Validation Rule: Must match pattern [A-Za-z0-9].{2,30} (3-31 characters, starting with alphanumeric)
Example: "HL7Spy"
9. Authors Field [9]
Purpose: Names of the individuals or teams who created or maintain this schema package.
Example: "HL7Spy Team"
10. Summary Field [10]
Purpose: Brief description or summary of the schema package purpose and contents.
Example: "Standard for Use of HL7 Version 2 in the UK"
11. Notes Label [11]
Purpose: Indicates the location of the notes section for detailed description, notes, or documentation about the schema package.
3.2 Field Override Control - User Documentation
Overview
The Field Override Control is a comprehensive interface for managing HL7 field definitions and overrides within the Schema Editor. This control allows users to create, modify, and manage field definitions for both standard HL7 segments and custom Z-segments.
1. Field Button [1]
Purpose: Add a new field override to the current schema
Shortcut: Ctrl+A
Functionality:
Creates a new field row in the grid
If a field is currently selected, the new field will be added to the same segment with the next available sequence number
Automatically focuses on the Path column for immediate editing
Supports both standard HL7 fields and custom Z-segment fields
2. Segment Button [2]
Purpose: Add a complete new segment definition with multiple fields
Functionality:
Opens a dialog to specify segment name (must be 3 characters)
Allows setting a description for the segment
Creates multiple empty fields (0 through specified count)
Automatically sets the first field (field 0) with the provided description
Updates the schema override collections
3. Import Button [3]
Purpose: Import field definitions from clipboard data
Functionality:
Opens an import dialog to process clipboard data
Best results when copying tables from Excel
Merges with existing field definitions
Updates existing fields if path matches
Adds new fields for unmatched paths
Tip: Copy the table from Excel for best results when importing field definitions.
4. Search Field [4]
Purpose: Search and filter field definitions
Shortcut: F5
Functionality:
Real-time search across all field properties
Includes clear and search buttons
Filters the grid view as you type
Case-insensitive search
5. Path Column [5]
Format: Segment-Sequence (e.g., "MSH-1", "PID-3", "ZU1-0")
Validation: Must be valid HL7 path format
Mask: Three letters, hyphen, followed by digits
Auto-population: When changed, automatically updates other field properties from base schema
6. Data Type Column [6]
Purpose: Specifies the HL7 data type for the field
Editor: Dropdown with available data types from base schema
Examples: ST, ID, CE, XPN, IS, TS, etc.
7. Description Column [7]
Purpose: Human-readable description of the field
Usage: Free-text field for documentation
Examples: "UK Additional Data", "Date of decision to admit.", "Coding status."
8. Length Column [8]
Purpose: Normative length specification
Format: Range format (e.g., "1..250", "0..*")
Mask: Optional range pattern
9. Conf Length Column [9]
Purpose: Conformance length specification
Format: Number with modifier (e.g., "250=", "100#")
Mask: Optional number with = or # modifier
10. Optionality Column [10]
Purpose: Field requirement level
Editor: Dropdown with standard HL7 optionality values
Values: R (Required), O (Optional), C (Conditional), etc.
Example: "O" indicates the field is optional
11. RP/# Column [11]
Purpose: Repetitional - number of times field can repeat
Format: Y (unlimited) or specific number
Mask: Y, y, or numeric value
12. Code Table Column [12]
Purpose: Associates field with a code table
Editor: Dropdown with available code tables
Auto-creation: Creates new code table if name doesn't exist
Example: "ZU010" indicates the field values must come from the ZU010 code table
Keyboard Shortcuts and Navigation
Available Shortcuts
Ctrl+A- Add new fieldF5- Focus search fieldDelete- Delete selected field (when row is focused)Enter- Move to next cell or rowTab- Move to next editable cell
Import Fields into Segment Form
Overview
The Import Fields into Segment dialog allows you to import and map field data from external sources (such as Excel, CSV, or clipboard data) into HL7 segment definitions. This tool is essential for creating custom HL7 schemas by mapping external field definitions to standard HL7 field properties.
This section references numbered elements [1] through [6] that correspond to specific UI components in the Import Fields into Segment dialog. Each numbered element is documented below with its exact location and functionality.
1. Segment Name Field [1]
Purpose: Enter the HL7 segment identifier that will be used for the imported fields.
Validation: Must be a valid HL7 segment name (3 characters, alphanumeric).
Example: "ZU1" (as shown in the image)
Usage: Enter the name of the segment that will be used for all HL7 Fields
2. Element Name / Description Field [2]
Purpose: Provide a human-readable description of the segment being created.
Example: "UK Additional Data" (as shown in the image)
Usage: Enter a descriptive name that explains the purpose of this segment. This will be used in documentation and help identify the segment's purpose.
3. Clear Button [3]
Purpose: Reset all field mappings and clear the data grid.
Functionality: Removes all imported data and resets the grid to its initial state.
Usage: Click this button when you want to start over with a new import or clear all current mappings.
4. Table Header Row [4]
Purpose: The main configuration area where you map external field names to HL7 field properties.
Columns: The columns will vary based on the table you have pasted into the Grid
Usage: Each column header contains a dropdown that allows you to map external field names to the appropriate HL7 field property. Each column must be mapped to a specific field, or set to (don’t map) to ignore the field entirely.
5. Dropdown Selection [5]
Purpose: Choose how to map external field data to HL7 field properties.
Available Mapping Options:
(don't map): Skip this field during import
CodeTableName: Map to code table name
ConfLength: Map to conformance length
DataType: Map to data type
Description: Map to field description
NormativeLength: Map to normative length
Optionality: Map to required/optional status
Path: Map to HL7 path
Repetitional: Map to repetition indicator
Sequence: Map to sequence number
Usage: Click on any column header dropdown to select how that column's data should be mapped to HL7 field properties.
6. Validate Button [6]
Purpose: Validate all field mappings and check for errors before importing.
Validation Checks:
Ensures all required columns are mapped
Validates data types against the schema
Checks for duplicate sequences or paths
Verifies HL7 path format (if using path mapping)
Usage: Click this button after configuring your mappings to check for any issues. The OK button will only be enabled after successful validation.
Step-by-Step Usage Guide
Step 1: Configure Segment Information
Enter a valid HL7 segment name in the Segment Name field [1]
Provide a descriptive name in the Description field [2]
Step 2: Import Data
Copy your field data from Excel, CSV, or other sources
Right-click in the data grid and select "Paste (Enhanced)" from the context menu or use the short-cut Cntrl-V.
The system will automatically detect column headers and populate the grid
Step 3: Map Fields
Click on each column header dropdown in the Table Header Row [4]
Select the appropriate mapping option from the Dropdown Selection [5]
Map at minimum: Sequence (or Path) and DataType
Set unmapped columns to "(don't map)"
Step 4: Validate and Import
Click the Validate button [6] to check for errors
Review any error messages and fix issues
Click OK to import the fields into your schema
Data Import Formats
Supported Import Formats:
Excel/CSV: Copy and paste from Excel or CSV files
HTML Tables: Copy from web pages or Word documents
RTF Tables: Copy from Rich Text Format documents
Plain Text: Tab or comma-separated values
Field Mapping Requirements
Required Mappings:
You must map at least one of the following:
Sequence: For numeric sequence-based fields (1, 2, 3...)
Path: For HL7 path-based fields (ZU1-1, ZU1-2...)
Additionally, you must map:
DataType: The HL7 data type for each field. A blank field will default to the “Withdrawn from Standard' ('-') DataType.
Validation Rules
Segment Name Validation
Must be exactly 3 characters
Must be alphanumeric
Field Mapping Validation
All columns must be mapped or set to "(don't map)"
Sequence numbers must be unique integers
Alternatively, HL7 paths must be valid format (e.g., ZU1-1, ZU1-2)
Data types must exist in the schema
Keyboard Shortcuts
Ctrl+V: Paste data from clipboard
Ctrl+S: Save (if applicable)
Delete: Remove selected rows
Tab: Navigate between fields