Output Contracts：有效 JSON 只是輸出契約的一半

A response can be valid JSON and still give a downstream consumer the wrong shape. A Markdown handoff can read fluently while omitting the one section the next engineer needs.

Those are concrete interface failures. They deserve checks that say which field or section broke the agreement.

Output Contracts is a small Python validator for explicit Markdown and JSON requirements. It does not call a model, score the writing, or silently repair the output.

Write down the consumer requirement

Imagine a work handoff that must contain these sections in order:

1. Summary
2. Evidence
3. Unresolved questions
4. Next steps

A handoff that omits unresolved questions and moves evidence below the next steps might be readable, but it no longer follows the agreed interface. The bundled Markdown contract declares required headings, ordering, and a forbidden completion phrase.

The last rule has a narrow meaning. Banning Everything is complete. can enforce a wording constraint. It cannot determine whether the work is actually complete or whether another phrase makes an equally unsupported claim.

Validate the bad handoff

Use Python 3.11 or newer. There are no third-party runtime dependencies:

git clone https://github.com/asadani/output-contracts.git
cd output-contracts
out_dir="$(mktemp -d)"

python -m output_contracts validate \
  fixtures/handoff-contract.json fixtures/handoff-bad.md \
  --format markdown --out "$out_dir/handoff-review.md"

python -m output_contracts inspect fixtures/handoff-contract.json

Validation exits with status 1 because the fixture violates the contract. The report identifies the missing section, the ordering problem, and the forbidden phrase. inspect validates the contract itself and prints its normalized summary.

A clean validation returns 0. Invalid contracts, unreadable input, and command errors return 2, so a calling script can distinguish a rejected output from a broken validation operation.

Check values as well as syntax

The JSON example requires an identifier, a constrained status, an integer count, and a non-empty items array. The bad fixture includes:

{
  "id": "case-18",
  "status": "accepted",
  "count": true,
  "items": []
}

This parses as JSON. It still violates two declared requirements: true does not satisfy the integer type, and an empty array does not satisfy the minimum item count.

Run both versions:

python -m output_contracts validate \
  fixtures/result-contract.json fixtures/result-bad.json \
  --format json --out "$out_dir/bad-result-review.json"

python -m output_contracts validate \
  fixtures/result-contract.json fixtures/result-good.json \
  --format markdown --out "$out_dir/good-result-review.md"

The adverse example exits with 1; the good example exits with 0. Fields use JSON pointers, and null remains distinct from a missing field.

Keep the contract proportionate

The current implementation is deliberately small. Markdown heading checks recognize ATX headings outside fenced code; they do not treat bold text or HTML as headings. Forbidden patterns scan the full output, including code blocks.

That detail can create false positives. A tutorial quoting a forbidden phrase in an example may need a different contract from a handoff that must never contain it. Patterns come from trusted contract authors, and complex regular expressions are not sandboxed or guaranteed to run in linear time.

For general JSON Schema validation, an established validator may fit better. This project is a compact option for a bounded workflow that needs both report-oriented Markdown checks and a small set of JSON field constraints.

Validate before the next operation

Put structural validation at the point where another person or program consumes the output. Save the report and route violations for correction. Keep content review separate: a required Evidence section can still contain a false statement, and a correctly typed count can still be wrong.

Start with one recurring failure that costs someone time. Add a rule for it, check useful and adverse examples, and watch for false positives before adding more constraints.

The MIT-licensed repository includes the fixture contracts, format reference, and validator. Its useful promise is precise feedback about declared rules.

AI disclosure: This article was drafted with AI assistance using the project's code and fixtures. Passing these checks establishes structural conformance, not factual correctness.