Connection overrides
One base spec, adapted per customer — a partial-spec overlay merged onto the pinned version at load time.
A connector spec is a shared template. Sometimes one customer needs to differ — a smaller page size, an extra output column, a slightly different mapping — without forking the whole connector. A connection override is a partial spec merged onto the connection's pinned base version at load time.
effective spec = merge(pinned base version, connection override) → validate → runThe base version stays immutable and shared; the delta lives on the connection.
Writing an override
An override is shaped like a partial ConnectorSpec — you write only the fields you're changing. To halve the page size for one customer:
resources:
- key: deals
fetch:
pagination:
pageSize: 25To add a typed column and tighten the rate limit:
defaults:
rateLimit:
requestsPerSecond: 2
resources:
- key: deals
output:
fields:
- { name: REGION, type: string }Merge semantics
The merge is spec-aware, not a naive deep merge:
| Override value | Result |
|---|---|
| scalar (pageSize, an expression, RPS) | replaces the base value |
| object | deep-merged recursively |
keyed array — resources (by key), enrich (by id), output.fields (by name) | merged by that key: same-key items deep-merge, new-key items append |
plain array (e.g. retry.retryOn) | replaces wholesale |
null | deletes that key |
So overriding one resource's pageSize leaves its siblings untouched, and adding
one output.field adds to the list rather than replacing it.
Transform is replace, not extend
transform.expression is a single JSONata string, so an override replaces it
rather than extending it. To add mapped fields, supply the full replacement
expression. Typed output.fields, by contrast, genuinely merge by name.
Validation at save time
When you save an override, Siphon merges it onto the base and runs the full validator on the result — a broken overlay is rejected immediately, not at the next run. The connection detail page's overrides editor live-validates the merged spec as you type.
Where it applies
The overlay is merged in every path that loads a connection's spec to run it — the durable worker and the interactive path alike — so a scheduled run and a manual run both see the same effective spec.
Editing an override re-applies automatically
Because the effective-spec checksum includes the override, changing one triggers auto-invalidation on a client-hash resource — the next run reprocesses all records with the new mapping, no manual reset needed.