x12-tidy

Validate and repair malformed ANSI X12 EDI, built piece by piece. The free CLI and Python library behind TidyEDI.

x12-tidy parses permissively and reports strictly: it locates the interchange envelope even in a malformed file and emits a Diagnostic for every deviation from the standard rather than bailing on the first. As it grows, each piece also reconstructs the structure it parsed into a clean, conformant form — so the end state is not just "here is what is wrong" but "here is a fixed copy." The audience is a developer who received a bad file from a trading partner and needs to know exactly what is non-conformant. (If "X12 linter" is what you searched for, yes, that too.)

Docs

Engineering notes — the method, then one note per piece of the parse, at docs.tidyedi.com:

• The x12-tidy Method — the one idea: earn the delimiters from structure first, then the rest is easy
• Finding the Elusive ISA Line — locating the ISA line when fixed byte offsets and a regex both fail
• Those Pesky Delimiters — reading the four delimiters from a line whose byte offsets have moved
• Reconstructing the ISA Line — rebuilding the canonical 105-byte line once the delimiters are trusted
• Reassembling the Interchange — splitting the body into segments and rejoining it with the ISA line into one payload
• Auditing the Envelope — checking whether the interchange's own bookkeeping (pairing, counts, control numbers) is honest

Using it — docs/using-x12-tidy.md: the CLI, the tidy() one-call API, the lower-level building blocks, and formatting your own report.

Reference — design.md (architecture, the diagnostic-code scheme) · docs/diagnostics.md (every code, generated) · the docs/ folder holds the Markdown sources and PDFs.

Status

Usage

pip install x12-tidy       # or: uv add x12-tidy

x12-tidy check path/to/file.edi      # run the checks built so far
x12-tidy codes --area isa            # list diagnostic codes
x12-tidy explain isa.leading-bytes   # detail for one code

check exit codes: 0 clean (or warnings only), 1 a fatal/error finding, 2 usage / IO problem.

Development

uv sync --extra dev
uv run pre-commit install     # once per clone: guards main, regenerates docs
uv run pytest
uv run python scripts/gen_diagnostics_docs.py   # after changing codes.py

All work goes on a feature branch and merges via PR — the no-commit-to-branch hook blocks direct commits to main. Cutting a release: docs/RELEASING.md.

Design conventions:

• Pure functions over bytes, never str.
• Diagnostic codes are area.specific names defined only in src/x12_tidy/diagnostics/codes.py; reference Code.* symbols, never code strings. Tests assert on the symbol.
• docs/diagnostics.md is generated; a pre-commit hook and a CI check keep it in sync with codes.py.

License

Apache License 2.0 — © 2026 Michael Schertz. See NOTICE.

"TidyEDI" and the TidyEDI logo are trademarks of Michael Schertz; the license covers the code, not the name or the mark.