Skip to content

Snapshot Format

Defaults files, live snapshots and patches all share one JSON schema, schema_version: 1, parsed strictly.


{
"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
}
}
}
FieldRequiredMeaning
schema_versionyesExactly 1
versionyesPositive 64-bit integer; must exceed the receiver’s accepted version
published_atnoRFC 3339 UTC timestamp, informational
knobsyesObject mapping knob names to definitions

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:

  1. It contains only the knobs that changed.
  2. A knob mapped to null is 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.


The parser rejects the whole document, never part of it, when it finds:

  1. Invalid JSON or invalid UTF-8.
  2. A missing required field, or a field of the wrong JSON type.
  3. Any unknown field, at the top level or inside a definition.
  4. A duplicate key: top-level field, knob name or group name.
  5. An invalid knob name or group name.
  6. A value that is not a JSON integer, such as true or 1.0, or one outside the signed 64-bit range.
  7. rollout_pct outside 0–100, or a group override that is neither an integer nor {"rollout_pct": N}.
  8. A rollout_value without a percentage, or a percentage without a rollout_value.
  9. More knobs than the receiver’s max_knobs (default 100,000).
  10. 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.


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.