Make assumptions explicit.
Declare object fields, required keys, primitive types, nested arrays, enum values and whether unknown fields are accepted.
CASE STUDY / INTEGRATION RELIABILITY
Workflow Contract Gate.
A small contract-testing CLI for the seams between APIs, webhooks and automation steps. Define the payload you rely on, save representative fixtures, and fail CI before a breaking change reaches the workflow.
THE PROBLEM
Integrations break at the boundary nobody wrote down.
A webhook can keep returning valid JSON while silently changing a field type, dropping a required key, adding an unsupported event, or introducing structure the next automation step cannot accept. When those assumptions exist only in a workflow editor or a developer's memory, regressions arrive in production.
Design constraint
Keep the contract format intentionally smaller than full JSON Schema. The tool should be understandable in one review, produce no payload-value leaks by default, and return stable exit codes for CI and automation.
Contract, fixture, gate.
Test representative payloads.
Validate one saved request/response or a directory of fixtures from staging, webhook samples or API adapters.
Turn drift into a build signal.
Valid fixtures exit 0, contract violations exit 1, and malformed contract/input configuration exits 2.
Small rules, useful diagnostics.
REQUIRED FIELDS
Missing keys fail at the exact path
A missing nested property is reported with its JSON path instead of a generic validation error.
TYPE SAFETY
Booleans are not integers
Python's type quirks are handled explicitly so true cannot accidentally satisfy an integer contract.
ENUMS
Unexpected events stay visible
Allowed event names or states can be bounded without exposing the rejected value in diagnostics.
UNKNOWN FIELDS
Strict only where you want it
Each object boundary can allow new fields or reject them, depending on how fragile the downstream consumer is.
ARRAY PATHS
Item failures point to the index
Nested list violations identify paths such as $.payload.tags[1] for fast triage.
SECRET HYGIENE
Report rules, not values
Default diagnostics contain paths, violation codes and rule messages. Fixture values are not echoed into CI logs.
A contract gate that fits in a pipeline.
$ workflow-contract-gate check --contract contract.json fixture.json
PASS fixture.json
$ workflow-contract-gate check --contract contract.json bad.json
FAIL bad.json
$.payload.email [missing_required] required field is missing
$.payload.id [type_mismatch] expected integer
exit 1
PASS fixture.json
$ workflow-contract-gate check --contract contract.json bad.json
FAIL bad.json
$.payload.email [missing_required] required field is missing
$.payload.id [type_mismatch] expected integer
exit 1
The same check can emit JSON for a larger monitoring system or run across every *.json fixture in a directory. The public repository includes passing and deliberately failing fixtures plus a GitHub Actions matrix.
Observed drift and explicit contracts solve different problems.
Data Shape Guard
Infers what real JSON/JSONL data looks like and compares observed shape or presence drift between datasets.
Workflow Contract Gate
Starts from a deliberate contract and asks whether saved API/webhook fixtures still satisfy that boundary.
Used together
Observed production/staging data can inform a contract; the explicit contract can then become a lightweight release gate.
Have an integration that breaks when one field moves?
I can turn the assumptions at an API, webhook or automation boundary into a small, reviewable validation gate and regression fixture set.