Manifest Diffing Patterns

Manifest diffs power safe rollouts. Combine CLI output with catalog metrics for maximum clarity.

CLI Diff

node proto.js diff \
  --from manifests/datasets/user_events-v1.json \
  --to manifests/datasets/user_events-v2.json \
  --generate-migration

Sample output:

{
  "changes": [
    { "path": "schema.fields.email.required", "from": false, "to": true }
  ],
  "breaking": [
    { "path": "schema.fields.email.required", "reason": "required flag changed" }
  ],
  "migration": {
    "steps": ["-- BACKFILL email column", "-- enforce NOT NULL"]
  }
}

Catalog Guardrails

const next = createDataProtocol(nextManifest);
const prev = createDataProtocol(prevManifest);

const diff = prev.diff(next.manifest());
const migration = prev.generateMigration(next.manifest());

Feed diff into change reviews, and store migration output alongside database runbooks.

Tips

• Always validate both versions before diffing to avoid noisy outputs.
• Track schema_hash and field_hashes (auto-generated) to detect tampering.
• Store diff artifacts in CI for auditors.