dlt Schema Contract Verdict

Decides what your dlt schema_contract will SILENTLY LOSE when an upstream changes shape. Pure function: no I/O, no warehouse connection, no dependency on dlt.

Built for dlt 1.29.1 (Apache-2.0). Not affiliated with or endorsed by the dltHub project.

THE MEASUREMENT. A source that had been sending {id, amount} starts sending a string in amount and adds a field nobody asked for:

  evolve         2 rows. amount is NULL for row 2 -- the value went to amount__v_text. new_col and secret_ssn auto-created.
  freeze         RAISES. The only loud option.
  discard_row    1 row. Row 2 vanished. Load reported success.
  discard_value  2 rows. amount NULL. The value vanished.

SELECT SUM(amount) RETURNS 100 UNDER ALL THREE NON-FREEZE OPTIONS. Three different losses producing one identical wrong answer, with the load reporting success every time -- and evolve is dlt's DEFAULT.

WHAT EACH ONE DOES. Under evolve a type change does not fail: dlt creates a second column and leaves the original NULL for those rows, so every aggregate over it silently covers only the rows that kept the old type. Under discard_row the offending row is dropped in full -- and the rows most likely to be dropped are the anomalous ones somebody needed to see. Under discard_value the row survives with a NULL, which is indistinguishable from a value that was legitimately absent, so nothing downstream can tell a discarded measurement from one that was never taken.

THE COMPLIANCE CASE. Because evolve creates columns automatically, an upstream that begins sending personal or regulated data gets it written to the warehouse and into every backup taken afterwards. Measured: a secret_ssn field the pipeline had never seen was created and stored on the first run that contained it. That arrives as a SUCCESSFUL PIPELINE RUN, not as an incident.

IT REFUSES RATHER THAN GUESSES. An unknown contract returns NOT_DETERMINABLE and says why it matters. Same for a source whose drift capability is unknown, which is the normal state for an API you do not control. And it stays quiet where it should: a source that genuinely cannot add columns or change types never exercises the contract, and it says so specifically so you can stop reviewing the choice.

RECONCILIATION IS WHAT MAKES ANY OF IT DETECTABLE, and is reported alongside a real loss rather than on its own. Without a row-count reconciliation against the source or an alert on the null rate of a column you aggregate, every failure above is permanent and invisible: the pipeline is green, the dashboard is plausible, and the number is wrong.

VERIFIED: 20 tests, measured by running the suite, every mutation observed FAILING before restore -- including one that caught a gap in the TESTS rather than the code.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function evaluateSchemaContract(config: PipelineConfig): Verdict;

  export type SchemaContract = "evolve" | "freeze" | "discard_row" | "discard_value" | "unknown";
  export type Verdict = | { status: "SAFE";