schema-drift
Compares the schema of every file with a baseline and reports, per file, the fields that
were added or removed, changed type or became nullable, and likely renames. Use it to check
new deliveries before they break a load, and --fail-on to stop a CI job.
undatum schema-drift data.csv data.jsonl
undatum schema drift data.csv data.parquet --fail-on removed,type
undatum schema-drift deliveries/ --baseline schema.json --fail-on removed,type
undatum schema-drift "exports/2026-*.csv" -O markdown -o drift.md
The baseline is the first file unless --baseline names one. A baseline can be a data file,
the output of undatum schema FILE --json, a JSON Schema, or a Frictionless table schema.
Directories are scanned for data files; quote glob patterns so the shell does not expand
them.
Two files are compared with diff --schema (also
undatum schema diff OLD NEW).
How fields are compared
- Types are normalized (integer, number, boolean, date, datetime, string, object,
array) and inferred strictly from a sample of 10,000 records, like
undatum schema: a column is an integer only if every value is. A single text value in a number column is reported as a type change. - Nullability compares whether empty values (or
n/a,null,-) occur. Declared baselines without nullability information skip this check. - Renames pair a removed and an added field of the same type when their names are similar or at least half of their sampled values are the same. They are listed as candidates; the added and removed fields are still reported.
--fail-on takes added, removed, type, nullability or any; the command exits with
1 when a file has a matching change. --json prints the
undatum.schema-drift/1 document.
Reference
Reads: any readable format · Writes: report (see --format-out) · Memory: bounded: a sample of records per file · Engines: python
undatum schema-drift [OPTIONS] PATHS...
| Argument | Description |
|---|---|
PATHS... | Files, directories or glob patterns to check. (required) |
| Option | Description | Default |
|---|---|---|
--baseline TEXT | Baseline: a data file, undatum schema --json output, JSON Schema or Frictionless schema (default: the first file). | |
--fail-on TEXT | Exit with 1 on these changes: added, removed, type, nullability, any. | |
-O, --format-out TEXT | Report format: text (default), markdown, json. | |
-o, --output TEXT | Write the report to this file. | |
--table, --sheet TEXT | Table or sheet name for multi-table sources (Excel, SQLite, lakehouse). | |
--json | Print the result as one JSON document (same as --format-out json). |
See also shared options.