Schema drift

Connectors break loudly when a source changes its API, but they can also break quietly: a field gets renamed, a column disappears, a number starts arriving as a string. The sync still succeeds, but your mapping now under- or mis-populates. Schema drift detection watches the shape of the raw source records on every run and tells you the moment it changes.

How it works

On each run, Siphon observes the raw source records (before your transform) and records their field shape — every field name and its inferred JSON type (string, number, boolean, object, array, or mixed when a field arrives with more than one type). That shape is hashed and stored per resource.

The next run compares the freshly observed shape to the stored one:

• First run — the shape is recorded; no alert (there's nothing to compare to).
• Unchanged — nothing happens.
• Changed — the stored shape is updated and a schema.drift event fires with the exact diff: which fields were added, removed, or retyped.

Observation samples up to 500 records per resource — enough to see optional fields without scanning an entire backfill. Detection runs for every resource regardless of sync mode or change-detection settings.

Where you see it

• Connection detail → Change detection lists the observed source fields per resource and when the shape last changed.
• Host webhook — if you've configured a webhook (see Webhooks), a schema.drift event is delivered with the diff:

{
  "type": "schema.drift",
  "orgId": "…",
  "connectionId": "…",
  "runId": "…",
  "timestamp": "2026-08-03T12:00:00.000Z",
  "data": {
    "resourceKey": "workorders",
    "added": [{ "name": "priority", "type": "string" }],
    "removed": [{ "name": "urgency", "type": "string" }],
    "retyped": [{ "name": "assetId", "from": "number", "to": "string" }]
  }
}

What to do with a drift alert

A drift event is a prompt to check whether your connector spec still maps the source correctly:

• Added field you want — add it to the resource's transform and output.fields.
• Removed field you relied on — the source dropped it; update the mapping or the downstream consumer.
• Retyped field — adjust the typed output.fields column so casts stay clean.

Drift never fails a run — it's an early-warning signal, not an error.