fhir2padnext/GEMINI.MD

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

FHIR_PAD is a Python-based converter that transforms FHIR JSON bundles into PADneXt 2.12 XML format (German healthcare billing standard). The converter validates both input FHIR data and output PAD XML, producing detailed diagnostic reports.

Core Architecture

Main Components

1. fhir_to_pad_converter.py - Primary converter with validation pipeline

   • Validates FHIR JSON bundles (schema-based or structural checks)
   • Groups FHIR resources by patient/encounter or by Claim resource.
   • Maps FHIR resources to PAD billing positions
   • Generates PADneXt 2.12 compliant XML
   • Validates output against XSD schemas
   • Produces JSON diagnostic reports
   • Outputs declarative AUF (order) information to the console.

2. validate_padnext.py - Standalone PADneXt XML validator

   • Validates PADneXt 2.12 ADL/AUF XML files against XSD schemas
   • Accepts multiple XML/XSD pairs for batch validation

3. utils.py - Utility functions

   • Contains helper functions for date parsing, reference extraction, and other common tasks.

4. validation.py - Validation framework

   • Provides a framework for semantic and business rule validation of FHIR data.

Data Flow

FHIR JSON Bundle → Validation → Resource Grouping → Mapping → PAD XML Generation → XSD Validation → Report

Resource Grouping: If Claim resources are present, FHIR entries are grouped by (patient_id, claim_id). Otherwise, they are grouped by (patient_id, encounter_id). Each group becomes one <Rechnung> (invoice) in the PAD output.

Resource Mapping:

• If a Claim resource is present, its item entries are mapped to <goziffer> positions.
• If no Claim is present, the following FHIR resources are converted to billing positions:
  • Observation, MedicationAdministration, Procedure, ServiceRequest, DiagnosticReport
• ExplanationOfBenefit resources are used to enrich the JSON report with adjudication details.

Date Handling: Effective dates extracted from FHIR fields (effectiveDateTime, issued, authoredOn, date, meta.lastUpdated) determine the zeitraum (time period) for each billing case.

Common Commands

Convert FHIR to PAD XML

Basic conversion:

python3 fhir_to_pad_converter.py \
  --input-json Input.json \
  --output-xml output.xml

With validation and report:

python3 fhir_to_pad_converter.py \
  --input-json samples/fhir/sample_1/226844_1240059013-KaBr.json \
  --output-xml output.xml \
  --report-json report.json \
  --pad-xsd specs/padnext/padx_adl_v2.12.xsd

With header configuration:

python3 fhir_to_pad_converter.py \
  --input-json Input.json \
  --output-xml output.xml \
  --header-cfg header_config.json

Validate PADneXt XML

Single file:

python3 validate_padnext.py \
  samples/padnext/sample_1/00209999_20250805_ADL_000087_padx.xml \
  specs/padnext/padx_adl_v2.12.xsd

Multiple files:

python3 validate_padnext.py \
  file1.xml schema1.xsd \
  file2.xml schema2.xsd

Dependencies

• Python 3.11+
• Required: lxml (XSD validation), jsonschema (FHIR validation)
• Built-in: xml.etree.ElementTree, argparse, json, datetime, random

Install dependencies:

pip3 install lxml jsonschema

Directory Structure

samples/
  fhir/sample_1/       - Example FHIR JSON bundles
  fhir/sample_2/       - Example FHIR JSON bundle with Claim resource
  padnext/sample_1/    - Example PADneXt XML outputs (ADL/AUF)
specs/
  padnext/             - PADneXt 2.12 XSD schemas and documentation
    padx_adl_v2.12.xsd - ADL (billing) schema
    padx_auf_v2.12.xsd - AUF (order) schema
    padx_basis_v2.12.xsd - Base types
    padx_enums_v2.12.xsd - Enumerations
    documentation_de/  - German specification PDFs

Key Implementation Details

PAD Namespace

All PAD XML elements use namespace http://padinfo.de/ns/pad

Claim-driven Conversion

If a FHIR Claim resource is present in the input bundle, it is used as the primary source of information for generating the PADneXt <Rechnung>. The Claim.item entries are converted to billing positions, and information about the provider, insurer, and patient is extracted from the Claim and its referenced resources.

Header Configuration

Header fields (billing entity, service provider, recipient) can be configured via --header-cfg JSON. If a Claim resource is present, the information from the Claim will override the header_cfg.

Validation Modes

• FHIR: JSON Schema validation (if schema provided) or structural checks. A new validation framework in validation.py allows for custom semantic and business rule validation.
• PAD: XSD validation (if XSD provided) or well-formedness checks.

Report Structure

JSON reports contain:

• input.schema_validation_ok - FHIR validation status
• input.stats - Resource counts, date ranges, warnings, and ExplanationOfBenefit stats.
• output.schema_validation_ok - PAD validation status
• output.stats - Invoice counts, position counts, warnings.
• validation_warnings - A list of warnings from the custom validation framework.

AUF Log Output

The converter prints declarative information to the console that would be contained in a pad_auf.xml file, such as sender, recipient, and the number of invoices.

Important Functions

• group_entries() - Groups FHIR resources by (patient_id, claim_id) if a Claim is present, otherwise by (patient_id, encounter_id).
• claim_item_to_position() - Maps a Claim.item to a PAD billing position.
• claim_to_rechnung_header() - Extracts header information from a Claim resource.
• resource_to_position() - Maps other FHIR resources to a PAD billing position (fallback).
• build_pad_xml() - Main XML generation logic, now with support for Claim-driven conversion.
• run_validation() (in validation.py) - Runs all custom validation checks.
• find_resource_by_ref() (in utils.py) - Helper function to resolve references within a FHIR bundle.