driftpipev0.9.4docs for Sign in

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 0
driftpipe 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 age is 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

CodeMeaning
0no differences, or only differences below the fail-on threshold
1usage error: unknown flag, bad flag value, missing argument
2input error: file missing, unreadable, malformed JSON, timeout hit
3drift found at or above the fail-on threshold
4lock 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.