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. Available on PyPI:

python -m pip install shapewitness
# Isolated CLI alternatives:
uvx shapewitness --help
pipx install shapewitness

For a source checkout, use python -m pip install .. Pin a version or reviewed commit for reproducibility. 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. Opt into --number-mode syntax for integer versus fractional/exponent witnesses; see the numeric feature model.

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