x12sdk

Typed Pydantic v2 models and a streaming SDK/CLI for HIPAA ASC X12 5010 health care transactions.

x12sdk is the maintained continuation of LinuxForHealth x12, which stopped at 0.57.0 in June 2022. It runs on Pydantic v2 and Python 3.10–3.13.

Supported transaction sets:

Every transaction is parsed into a validated Pydantic model and can be serialized back to X12; the test suite asserts that round trip reproduces each sample file byte for byte.

Install

pip install x12sdk

From source:

git clone https://github.com/owgreen-dev/x12sdk
cd x12sdk
python3 -m venv .venv && source .venv/bin/activate
pip install --upgrade pip
pip install -e .

SDK

The x12sdk.io module streams either raw segments or validated transaction models from a file.

Stream segments (each segment becomes its name plus a list of fields):

from x12sdk.io import X12SegmentReader

with X12SegmentReader("/home/edi/270.x12") as r:
    for segment_name, segment_fields in r.segments():
        print(segment_name, segment_fields)

Stream models (the payload is validated; one model per transaction set):

from x12sdk.io import X12ModelReader

with X12ModelReader("/home/edi/270.x12") as r:
    for model in r.models():
        print(model.header)   # common attributes: header, footer
        print(model.footer)
        model.x12()           # serialize back to X12

CLI

x12sdk --help
usage: x12sdk [-h] [-s | -m] [-x] [-p] [-d] file

The x12sdk CLI parses and validates X12 messages.
Messages are returned in JSON format in either a segment or transactional format.

positional arguments:
  file              The path to a ASC X12 file

options:
  -h, --help        show this help message and exit
  -s, --segment     Returns X12 segments
  -m, --model       Returns X12 models
  -x, --exclude     Exclude fields set to None in model output
  -p, --pretty      Pretty print output
  -d, --delimiters  Include X12 delimiters in output (model mode only)

x12sdk -s -p demo-file/demo.270   # segments
x12sdk -m -p demo-file/demo.270   # models

Migrating from linuxforhealth-x12

See CHANGELOG.md for everything that changed.

Development

pip install -e ".[dev]"
ruff check src
pytest --cov

Contributions are welcome; see CONTRIBUTING.md (Apache-2.0, DCO sign-off, no copyrighted standards text, no real PHI). To add a transaction set, see repo-docs/NEW_TRANSACTION.md; the design is described in repo-docs/DESIGN.md.

Provenance and related work

x12sdk is a fork of LinuxForHealth x12 by Dixon Whitmire and the LinuxForHealth contributors (IBM), released under the Apache License 2.0. The models, parser, readers, and test corpus originate there; x12sdk exists to keep that work usable on current Python and Pydantic. The original LICENSE is retained, and attribution and trademark notes are in NOTICE and TRADEMARK.md. x12sdk is not affiliated with or endorsed by IBM, LinuxForHealth, or the Linux Foundation.

• MdClarity/x12 — an independent fork by MD Clarity (Cary Lee) that completed a Pydantic v2 migration and added type checking and fuzzing in 2026. x12sdk's port is written separately from the 2022 upstream; their work is acknowledged here and their fixes are welcome upstream in x12sdk.
• pyx12 — the long-standing Python X12 validator/converter (XML/dict output, map-driven). Choose pyx12 for validation against X12 maps; choose x12sdk for typed Python models.
• edi-835-parser — a popular 835-only parser with pandas output.

License

Apache License 2.0. See LICENSE and NOTICE.