Guides

Validating with JSON Schema

Give a bin a JSON Schema and every write is checked before it's stored.

Give a bin a JSON Schema and every publish, promote and rollback is checked against it before it's stored. A payload that doesn't match is refused, so a typo or a wrong type never reaches your users.

Adding a schema

When you create the bin:

terminal
hotcfg bins create mobile-flags --schema schema.json

Or later, in the dashboard: open the bin, then the Schema tab. From then on the Payload editor checks your JSON against the schema as you type, lists the errors under the editor, and keeps Publish disabled until they're fixed.

What a refusal looks like

The CLI points at the line and the rule:

terminal
$ hotcfg push flags.json --bin mobile-flags --env staging
error: flags.json does not match the schema of bin mobile-flags (1 error)

  flags.json:3  /limits/max_upload_mb
    rule:    /properties/limits/properties/max_upload_mb/type
    message: expected integer, but got string

Over HTTP the answer is 422 schema_validation_failed with a list of errors, each with the JSON pointer of the offending field, so editors can underline it.

Changing a schema

A new schema must accept the current payload of every environment. Otherwise the change is refused, with the payloads it would reject. Change the payloads first, or relax the schema in two steps.

A schema can be at most 64 KiB. Validation is also limited to 3 million subschema checks per payload, so a schema can't make writes slow: one whose $refs or allOf/anyOf/oneOf multiply the work is refused when you save it (invalid_schema), or, if the blow-up only shows on a deeply nested payload, the write is refused (schema_too_complex). Ordinary schemas stay far below it, even on a 2 MB payload.

Last updated 16 November 2026