SchemaLinter-OneShot: Building a CLI Tool for Forcing LLM JSON Schema Validation and Self-Healing

A developer built SchemaLinter-OneShot, a Python standard-library CLI tool that validates LLM JSON output against a schema and attempts self-healing of malformed responses. The project was closed as development incomplete after the author found that argparse flushes plain-text usage errors to stderr before a try/except SystemExit block can convert them into JSON, and that the same hook also swallows the exit code 0 from --help. The writeup documents the argparse lifecycle pitfalls as anti-patterns for future JSON-only CLI designs.

"SchemaLinter-OneShot" was designed as a lightweight, one-shot linter built entirely on the Python standard library, purposely eliminating excessive dependencies like heavy external validation libraries. extract json json ... fenced code blocks. { to the last } . validate types jsonschema , it recursively scans the payload to ensure the presence of required keys and performs minimal, strict type checking. The implementation appeared beautifully cohesive. However, during the QA phase, when implementing the requirement to "format error handling into JSON when arguments are missing," I fell into a deep quagmire caused by the internal specifications of the standard framework. When executing the script without arguments, instead of the intended JSON-formatted error, the default plain-text usage error from argparse leaked into the standard error stream. bash $ python3 V2 PROD 20261007 030033 test.py usage: V2 PROD 20261007 030033 test.py -h -s SCHEMA -i INPUT --mode {strict,prompt} V2 PROD 20261007 030033 test.py: error: the following arguments are required: -s/--schema 💡 For immediate deployment: The complete source code suite ZIP for this architecture is available on Gumroad https://phenox.gumroad.com/l/lreerh for $0+ Pay What You Want . On the development side, I took the approach of catching the error using a try...except SystemExit: block to intercept the termination and convert it into a JSON payload before exiting, as shown below: try: args = parser.parse args except SystemExit: print json.dumps { "status": "error", "message": "Argument parsing failed. Required argument '-s/--schema' is missing." }, ensure ascii=False sys.exit 2 However, this approach contained two fatal oversights regarding the lifecycle of the Python argparse module : argparse detects missing required arguments or invalid options, it outputs a usage message directly to sys.stderr via its internal error method SystemExit . except block to output the JSON payload, the plain-text error message had already been flushed to the standard error stream. --help -h with Validation Errors SystemExit 0 after successfully displaying the help message. except SystemExit: implementation above, Following the feedback from QA, I had to acknowledge the architectural limitations of relying on exception hooking within argparse . To build a truly robust JSON-only CLI, extensive refactoring would be required: argparse.ArgumentParser class. sys.argv prior to parsing to insert an explicit, decoupled validation layer upfront. However, the initial requirement for this tool was to be a "lightweight, one-shot tool that operates reliably within one second to ensure CI/CD pipeline health." Continuously expending engineering effort on hacking standard frameworks at the primitive layer of CLI argument parsing would severely degrade the project's Return on Investment ROI . Making a comprehensive architectural judgment, I decided to avoid complicating the codebase with brittle patches in this version V2 . Consequently, I chose to temporarily close the project as Development Incomplete , extracting the technical debt and passing the accumulated knowledge on to future designs. The architectural insights gained from this challenge will serve as valuable anti-patterns for future CLI tool development. If this engineering log saved your production server and your sanity , consider supporting our architecture on GitHub Sponsors.