validedi 0.1.0

X12 EDI Parser and Validator for Healthcare Transactions

ValidEDI

A Python library for parsing and validating healthcare X12 EDI transactions.

Supported Transaction Types

• 837P - Professional Health Care Claims
• 837I - Institutional Health Care Claims
• 835 - Health Care Claim Payment/Advice (Remittance)
• 834 - Benefit Enrollment and Maintenance

Features

• ✅ Auto-detection: Automatically detects transaction type and delimiters
• ✅ YAML-driven: Configuration via YAML files, not hardcoded logic
• ✅ Comprehensive Validation: Regex, code sets, cross-segment checks, and custom handlers
• ✅ Type-safe: Full type annotations with Pydantic v2 models
• ✅ Fast: Optimized parsing with minimal overhead
• ✅ Loop Hierarchy: Proper hierarchical loop structure based on X12 standards
• ✅ Extensible: Easy to add new transaction types and validation rules

Installation

pip install validedi

Quick Start

from validedi import parse, validate

# Parse an EDI file
with open('claim.edi', 'r') as f:
    raw_edi = f.read()

# Parse only (fast, no validation)
parsed = parse(raw_edi)
print(f"Transaction type: {parsed.envelope.transaction_type}")
print(f"Sender: {parsed.envelope.sender_id}")
print(f"Number of loops: {len(parsed.loops)}")

# Parse and validate
result = validate(raw_edi)
print(f"Valid: {result.is_valid}")
print(f"Errors: {result.error_count}")
print(f"Warnings: {result.warning_count}")

# Show validation errors
for error in result.errors:
    print(f"[{error.severity}] {error.code}: {error.message}")
    print(f"  Location: {error.segment} element {error.element} at position {error.position}")

Loop Navigation

from validedi import parse

result = parse(raw_edi)

# Navigate loop hierarchy
for loop in result.loops:
    print(f"Loop {loop.loop_id}: {len(loop.segments)} segments")
    
    # Find specific segments
    clm = loop.find_segment('CLM')
    if clm:
        claim_id = clm.get_value(1)
        claim_amount = clm.get_value(2)
        print(f"  Claim {claim_id}: ${claim_amount}")
    
    # Access child loops
    for child in loop.children:
        print(f"  Child loop: {child.loop_id}")

Validation Rules

ValidEDI supports multiple types of validation rules:

• Regex: Pattern matching (dates, NPIs, codes)
• Code Sets: Valid value lists (place of service, adjustment codes)
• Expressions: Arithmetic comparisons (charge totals)
• Builtin Handlers: Complex logic (Luhn algorithm, cross-segment checks)

All rules are defined in YAML configuration files for easy customization.

Architecture

ValidEDI follows a three-layer architecture:

1. Library Layer (validedi/) - Core parsing and validation engine
2. Configuration Layer (YAML files) - Transaction definitions and rules
3. Handler Layer (Python) - Complex validation logic

This separation allows new transaction types to be added via YAML without code changes.

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Type checking
mypy src/validedi

# Code formatting
black src/validedi
ruff check src/validedi

Examples

See examples/basic_usage.py for comprehensive examples including:

• Parse-only mode
• Full validation
• Loop navigation
• Error handling

License

MIT