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

SchemaLinter-OneShot is a lightweight, one-shot CLI tool that enforces LLM JSON Schema validation and self-healing. It was designed using only Python's standard library, avoiding excessive dependencies. The tool uses regular expressions to extract JSON candidates from noisy LLM output, which can come from fenced code blocks, range extraction, or a fallback of parsing the entire raw text. For type validation, it recursively scans the payload to ensure required keys are present and performs strict type checking.

During QA testing, a fatal specification conflict was discovered. The tool failed to output JSON-formatted errors when arguments were missing. Instead, the default plain-text usage error from argparse was displayed in the standard error stream. This issue arose because argparse outputs usage messages directly to sys.stderr before raising the exception, which was caught and converted into a JSON payload.

Another issue was conflating the --help flag with validation errors, causing the JSON-formatted error message to overwrite the help documentation and severely impacting the user experience.

The development team realized that relying on exception hooking within argparse was not a viable solution for building a robust JSON-only CLI tool. To create a truly reliable and lightweight tool, extensive refactoring would be required, such as overriding the error() method of the argparse.ArgumentParser class or scanning sys.argv before parsing.

However, the initial requirement for the tool was to be lightweight and operate quickly within a CI/CD pipeline. Given the architectural limitations, the project was temporarily closed as [Development Incomplete], preserving the accumulated knowledge and lessons learned for future designs.