Observe real payloads.
Walk nested objects and every array element, record observed types, presence ratios and a small set of safe examples.
CASE STUDY / DATA RELIABILITY
Data Shape Guard.
A lightweight data-contract check for the stage where the payload is real, the schema is informal, and downstream breakage is expensive.
THE PROBLEM
“Valid JSON” can still break the system.
A webhook payload can remain syntactically valid while a field disappears, an integer becomes a string, or an almost-required property becomes sparse. Spot checks rarely catch those changes consistently. Full schema governance can also be too heavy for early-stage integrations and operational exports.
Design constraint
Keep deployment friction close to zero. No third-party runtime dependency, no mutation of source data, and reports must remain available even when CI intentionally fails.
Infer, compare, gate.
Classify drift.
Removed paths and type-set changes are high severity. Presence-ratio drift is medium. New fields are informational.
Choose what breaks CI.
Teams can report only, fail on high severity, fail on medium-or-higher, or fail on any detected drift.
The edge cases are part of the feature.
ARRAY COVERAGE
No silent first-N sampling
A type change that appears late in an array is still observed. The regression suite explicitly checks a change after the first 50 elements.
PATH SAFETY
Literal keys stay literal
Keys containing dots or array-like markers are escaped, preventing collisions between a literal key such as a.b and a nested path.
INPUT STRICTNESS
Reject ambiguous JSON
Duplicate object keys and non-finite values such as NaN or Infinity are rejected instead of being quietly normalized.
SECRET HYGIENE
Useful reports without leaking values
Examples under token, password, API-key, authorization and cookie-like paths are redacted, including unusual bracketed keys.
CI DIAGNOSTICS
Fail and still explain why
When the configured policy returns exit code 1, JSON and HTML reports have already been written and can be retained as CI artifacts.
COMPATIBILITY
Small operational footprint
The project targets Python 3.10+ and runs its regression suite across multiple supported Python versions in GitHub Actions.
A reviewable contract in two commands.
$ python data_shape_guard.py infer fixtures/baseline.jsonl
records=120 paths=37
$ python data_shape_guard.py compare fixtures/baseline.jsonl build/current.jsonl --fail-on high
drift=2
exit 1 when breaking drift matches policy
records=120 paths=37
$ python data_shape_guard.py compare fixtures/baseline.jsonl build/current.jsonl --fail-on high
drift=2
exit 1 when breaking drift matches policy
The default remains report-only for backward compatibility. Teams opt into CI failure behavior explicitly and can tune presence-ratio sensitivity with --required-drift-threshold.
Small tool, production-minded decisions.
Boundary thinking
Failure behavior, malformed inputs and accidental secret exposure are designed alongside the happy path.
Regression discipline
Edge cases are encoded as tests so a later refactor cannot silently erase the reliability work.
Client handoff
The CLI, exit codes, reports and documentation are shaped so another person can run and troubleshoot the tool without hidden context.
Need this pattern inside your own workflow?
I can adapt the same validation and failure-gating approach to API responses, webhooks, ETL exports or AI-agent tool outputs.