Snapshot Format
Defaults files, live snapshots and patches all share one JSON schema,
schema_version: 1, parsed strictly.
Live Snapshot
Section titled “Live Snapshot”{ "schema_version": 1, "version": 42, "published_at": "2026-10-09T09:16:59Z", "knobs": { "checkout:killswitch_new_path": { "default": 0 }, "search:max_results": { "default": 25 }, "payments:new_processor": { "default": 0, "overrides": { "employees": 1, "beta": { "rollout_pct": 50 } }, "rollout_pct": 10, "rollout_value": 1 } }}| Field | Required | Meaning |
|---|---|---|
schema_version | yes | Exactly 1 |
version | yes | Positive 64-bit integer; must exceed the receiver’s accepted version |
published_at | no | RFC 3339 UTC timestamp, informational |
knobs | yes | Object mapping knob names to definitions |
Defaults File
Section titled “Defaults File”A baked defaults file has the same shape without version and
published_at. It is always version 0; including either field is a schema
error.
{ "schema_version": 1, "knobs": { "checkout:killswitch_new_path": { "default": 0 } }}A patch, which a custom source
returns with is_patch = true or an HTTP endpoint returns as a diff, uses the
snapshot shape with two differences:
- It contains only the knobs that changed.
- A knob mapped to
nullis deleted from the live snapshot.
{ "schema_version": 1, "version": 43, "knobs": { "search:max_results": { "default": 50 }, "checkout:old_flag": null }}This follows JSON Merge Patch (RFC 7396) at knob granularity: each knob is replaced or deleted as a unit. A client always applies a patch onto its own last accepted live snapshot, never onto whatever base the sender claims, so a confused sender can at worst cause a rejected update, never a wrong merge.
Deleting a knob that also has a baked default makes readers fall back to the baked definition.
Strictness
Section titled “Strictness”The parser rejects the whole document, never part of it, when it finds:
- Invalid JSON or invalid UTF-8.
- A missing required field, or a field of the wrong JSON type.
- Any unknown field, at the top level or inside a definition.
- A duplicate key: top-level field, knob name or group name.
- An invalid knob name or group name.
- A value that is not a JSON integer, such as
trueor1.0, or one outside the signed 64-bit range. rollout_pctoutside0–100, or a group override that is neither an integer nor{"rollout_pct": N}.- A
rollout_valuewithout a percentage, or a percentage without arollout_value. - More knobs than the receiver’s
max_knobs(default 100,000). - A document larger than 16 MiB, or nested too deeply.
A rejected update is counted and logged by category, and the receiver keeps its last known good snapshot.
Wire Formats Beyond JSON
Section titled “Wire Formats Beyond JSON”The durable authority and managed agents use a narrow, versioned MessagePack schema for snapshots, exact-base deltas and progress records, inside bounded raw or zstd frames. It carries the same definitions plus per-namespace and per-key revisions. It’s an internal protocol between Detent components, not a publishing format; publishers speak JSON. See Delivery and Local Images.