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
Python 3.10+ with SQLite support. Available on PyPI:
python -m pip install shapewitness
# Isolated CLI alternatives:
uvx shapewitness --help
pipx install shapewitnessFor a source checkout, use python -m pip install .. Pin a version or reviewed
commit for reproducibility. See release guidance.
From a checkout:
shapewitness examples/events.jsonl -n 4 --report coverage.json > fixture.jsonl
# shapewitness: 4/6 rows; 19/19 observed features; completeLines 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.
Version 0.1.3 also compares baseline/current structural inventories for CI and keeps
known problem rows with SHA-256 checked pins. Try the complete
pytest + GitHub Actions regression case.
| I want to… | Start here |
|---|---|
| Use the CLI, pipes, or Python API | Usage |
| Build pytest fixtures, test ETL, or reproduce an importer bug | Recipes |
| Inspect a reproducible head/random comparison | Synthetic benchmark |
| Build a wheel or prepare a release | Release readiness |
| Understand null, missing, arrays, and tie-breaking | Feature model |
| Verify selected bytes and coverage explanations | Provenance |
| Check strict input rules, resource limits, and privacy | Limits & privacy |
| Understand the implementation or contribute | Architecture · Development |
| Work on this repository with an agent | Agent guide |
| Compare the scope with JSONLKit and jselect | Related tools |
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