Skip to content

Schemas & validation

v1 · Last updated 2026-07-17

Schemas & data validation

A template can carry a JSON Schema for its data payload, attached one of two ways (mutually exclusive — setting one nulls the other):

  • Saved — template.schemaId → a reusable tenant-scoped Schema row.
  • Inline — template.jsonSchema holds the document on the template. Good for one-offs.

Managed in the dashboard (Editor → Schema tab); API keys can read schemaId/jsonSchema but not manage schemas. The schema always drives JSON-path autocomplete in the editor; render-time validation is separate and opt-in via two template flags:

SettingDefaultBehaviour
validateDatafalseValidates every render payload against the schema. Failure returns 400 schema_validation_failed with per-field errors; nothing renders, no quota is used.
allowAdditionalDatafalseWith false, unknown top-level keys are rejected (catches typos). With true, extra fields pass through. Only applies while validateData is on.

Both flags live on the template — set them via PATCH /:id or in the Editor → Schema tab.

Validation failure payload

HTTP/1.1 400 Bad Request
{
  "error": "schema_validation_failed",
  "errors": [
    {
      "path": "/customer/email",
      "keyword": "format",
      "message": "must match format \"email\"",
      "params": { "format": "email" }
    },
    {
      "path": "/items/3/quantity",
      "keyword": "type",
      "message": "must be integer",
      "params": { "type": "integer" }
    }
  ]
}

path is a JSON Pointer into your payload. Bulk endpoints add itemIndex so you know which item broke; async jobs validate before the job is created, so a failing batch never produces a job.

Need help?

Open a ticket from the in-app Support page, or email [email protected].