ShapeWitness

Small JSONL fixtures that show the shapes your code needs to handle.

head -n 20 often gives you twenty happy-path rows. ShapeWitness keeps the records with missing fields, nulls, empty collections, and mixed types, then explains why each row was selected.

• Real records: original bytes, numeric precision, whitespace, and line endings
• Explainable coverage: observed structural features, uncovered gaps, source hashes
• Reproducible and local: deterministic selection, bounded disk spooling, no network calls

Install

Python 3.10+ with SQLite support. Install from a checkout:

python -m pip install .

Or directly from GitHub:

python -m pip install 'git+https://github.com/agent-axiom/shapewitness.git'

Pin a reviewed commit for reproducible source installations. See release guidance.

Ten-second demo

From a checkout:

shapewitness examples/events.jsonl -n 4 --report coverage.json > fixture.jsonl
# shapewitness: 4/6 rows; 19/19 observed features; complete

Lines 1, 3, 4, and 5 survive. See the input, selected fixture, and explanation. Use --require-complete to fail CI when the selected rows leave observed features uncovered.

Read next

Know the boundaries: this is greedy structural coverage, not a statistically representative sample, an optimal minimum set, or a schema guarantee. Selected rows retain private data; reports can expose property names. Details.

Documentation index · Contributing · Security · Changelog · MIT license