schema.go

// Copyright 2026 Joshua Jones <joshua.jones.software@gmail.com>
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//    http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package hl7

// FieldCheckFunc validates a field and returns any issues found.
// It runs once per repetition, after declarative checks.
type FieldCheckFunc func(Field) []Issue

// SegmentCheckFunc validates a segment and returns any issues found.
// It runs once per segment occurrence, after all field checks.
type SegmentCheckFunc func(*Segment) []Issue

// MessageCheckFunc validates a message and returns any issues found.
// It runs once per Validate call, after all segment checks.
type MessageCheckFunc func(*Message) []Issue

// Schema contains the definitions needed to validate HL7v2 messages.
// Each map is optional — only populated categories are validated.
// For example, a Schema with only Messages populated performs structure
// validation without checking field contents.
//
// Struct tags support unmarshaling from JSON (encoding/json), YAML, and
// TOML using the user's preferred decoder.
type Schema struct {
	Messages  map[string]*MessageDef  `json:"messages,omitempty"`   // keyed by structure ID, e.g., "ADT_A01"
	Segments  map[string]*SegmentDef  `json:"segments,omitempty"`   // keyed by segment type, e.g., "PID"
	DataTypes map[string]*DataTypeDef `json:"data_types,omitempty"` // keyed by type name, e.g., "CX"
	Tables    map[string]*TableDef    `json:"tables,omitempty"`     // keyed by table number, e.g., "0001"
	Checks    []MessageCheckFunc      `json:"-"`                    // message-level custom validators
}

// MessageDef defines the expected segment structure of a message type.
type MessageDef struct {
	Elements []Element `json:"elements"`
}

// Element represents a segment or group within a message structure.
// Exactly one of Segment or Group should be non-empty.
type Element struct {
	Segment  string    `json:"segment,omitempty"`  // segment type for segment entries, e.g., "PID"
	Group    string    `json:"group,omitempty"`    // group name for group entries, e.g., "INSURANCE"
	Min      int       `json:"min,omitempty"`      // minimum occurrences (0 = optional)
	Max      int       `json:"max,omitempty"`      // maximum occurrences (-1 = unbounded)
	Elements []Element `json:"elements,omitempty"` // children (for groups only)
}

// SegmentDef defines the expected fields for a segment type.
type SegmentDef struct {
	Fields []FieldDef       `json:"fields"`
	Check  SegmentCheckFunc `json:"-"` // custom validator run after field checks
}

// FieldDef defines the constraints for a single field within a segment.
// Index is 1-based following HL7 convention (Field(1) is the first field
// after the segment type).
type FieldDef struct {
	Index     int            `json:"index"`          // 1-based field number
	Name      string         `json:"name,omitempty"` // human-readable name, e.g., "Patient Identifier List"
	DataType  string         `json:"type,omitempty"` // e.g., "CX", "ST", "NM", "DT"
	Required  bool           `json:"required,omitempty"`
	Repeating bool           `json:"repeating,omitempty"`
	MaxLength int            `json:"max_length,omitempty"` // 0 = no limit
	Table     string         `json:"table,omitempty"`      // table number for coded values, e.g., "0001"
	Value     string         `json:"value,omitempty"`      // if set, field must equal this exact value
	Check     FieldCheckFunc `json:"-"`                    // custom validator run after declarative checks
}

// DataTypeDef defines the component structure of a composite data type.
// Primitive types (ST, NM, DT, etc.) do not need a DataTypeDef — their
// format is validated by built-in rules keyed on the type name.
type DataTypeDef struct {
	Components []ComponentDef `json:"components"`
}

// ComponentDef defines the constraints for a single component within a
// composite data type. Index is 1-based following HL7 convention.
type ComponentDef struct {
	Index     int    `json:"index"`          // 1-based component number
	Name      string `json:"name,omitempty"` // human-readable name
	DataType  string `json:"type,omitempty"` // primitive type name for format validation
	Required  bool   `json:"required,omitempty"`
	MaxLength int    `json:"max_length,omitempty"` // 0 = no limit
	Table     string `json:"table,omitempty"`      // table number for coded values
	Value     string `json:"value,omitempty"`      // if set, component must equal this exact value
}

// TableDef defines a set of valid coded values.
// Values maps code strings to human-readable descriptions.
type TableDef struct {
	Values map[string]string `json:"values"` // code -> description
}