driftpipe
Schema-drift detection for JSON record streams. One static binary, one exit code.
NAME
driftpipe - detect structural drift between a record stream and a committed schema
SYNOPSIS
driftpipe check [--schema PATH] [--input PATH] [--sample N] [--fail-on MODE] driftpipe snapshot [--schema PATH] [--input PATH] [--sample N] [--force] driftpipe explain [--schema PATH] [--path PATH] [--format MODE] driftpipe version
DESCRIPTION
driftpipe reads a stream of JSON records, works out what shape they actually have, and compares that shape to a lock file you committed earlier. If the structure moved, it says what moved and exits non-zero. That is the whole program.
It exists because the usual way of finding out that an upstream producer renamed a field is a dashboard going blank on a Sunday. A structural check is cheap enough to run on every pull request and in a nightly job against yesterday's data, and it catches the class of break that no amount of row-count monitoring will.
driftpipe never looks at values. It reads types and paths, and nothing else leaves the process except a diff. There is no server, no daemon, no database and no network input: one static binary, a file or standard input, an exit code.
EXAMPLE
$driftpipe check --schema schema.lock --input events.ndjson --sample 0driftpipe 0.9.4 48213 records 31 paths 182ms+ order.coupon_code string additive + order.items[].discount int additive ~ order.total int -> float widening ! order.customer_id string -> string|null nullability - order.legacy_ref string removed 5 differences: 2 additive, 1 widening, 2 breaking fail-on=breaking, exit status 3
Four symbols carry the whole report: + a path that is new in the stream, - a path the lock has and the stream does not, ~ a type that grew in a direction we consider safe, and ! anything else. The classification rules are fixed and documented; they are not heuristics and they do not look at field names.
WHAT IT IS NOT
- Not a validator. It will not tell you that
ageis negative or that an enum gained a member. Values are never inspected. - Not a migration tool. It detects drift and reports it; what you do about the schema afterwards is your problem.
- Not a data quality framework. No rules engine, no plugins, no extension points, no embedded language.
- Not a JSON Schema implementation. The lock format is its own thing and the mapping is lossy in both directions, as explained under limitations.
- Not a service. Nothing listens on a port, nothing phones home, and the binary makes no outbound connection of any kind.
EXIT STATUS
| Code | Meaning |
|---|---|
| 0 | no differences, or only differences below the fail-on threshold |
| 1 | usage error: unknown flag, bad flag value, missing argument |
| 2 | input error: file missing, unreadable, malformed JSON, timeout hit |
| 3 | drift found at or above the fail-on threshold |
| 4 | lock file unreadable, or written by a newer lock format |
Codes 3 and 2 are deliberately distinct. A job that treats “the file was not there” as “the schema is fine” will pass green for a month and then surprise you, so an unreadable input is never silently a success.
STATUS
Version 0.9.4, released 24 September 2026. The command line surface has been stable since 0.6.0 in April 2025; the lock format is at version 3 and has had one migration since. The zero major version is honest rather than modest: the lock format may change once more before 1.0, and when it does the tool will read the old one and tell you to re-snapshot.
Bug reports are welcome at bugs@driftpipe.sh, and the only thing we ask for is a reproducer: twenty records that show the problem, the lock file, and the exact command line. A description of what you expected is useful; a description without records is not.
Start with install, then usage for the complete flag list, or go straight to the CI recipes if you only want this wired into a pipeline and nothing more.