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](https://json-schema.org/) 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 `$ref`s 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
