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-scopedSchemarow. - Inline —
template.jsonSchemaholds 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:
| Setting | Default | Behaviour |
|---|---|---|
validateData | false | Validates every render payload against the schema. Failure returns 400 schema_validation_failed with per-field errors; nothing renders, no quota is used. |
allowAdditionalData | false | With 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].