JSON Schema Validator¶

The JSON Schema validator checks a JSON file against a JSON Schema document you provide. It's the right tool when you have — or want to write — a formal contract for the shape of a JSON payload.

It's particularly good for structural validation: required fields, data types, regex patterns on strings, allowed enums, array length and item types, nested object shapes. For cross-field or behavioural rules ("the discount must not exceed the subtotal"), pair it with the Basic validator or add step-level CEL assertions.

What you'll need¶

• A Validibot account with permission to author workflows.
• A workflow whose allowed file types include JSON.
• A JSON Schema document — either one you've written, one published by a standard (e.g. AsyncAPI, OpenAPI components, EnergyPlus epJSON), or one you generate from a sample payload.

Validibot supports draft 2020-12, draft 2019-09, draft-07, draft-06, and draft-04. If your schema declares a $schema keyword the validator will use that draft; otherwise it defaults to 2020-12.

Setting up a JSON Schema step¶

1. Open the workflow editor and click Add step.
2. Pick JSON Schema from the validator library.
3. Give the step a name like "Order envelope schema" and a short description.
4. Supply the schema one of two ways:
5. Paste inline — drop the schema JSON into the editor.
6. Upload — attach a .json file containing the schema.
7. Click Save step.
8. Open the saved step and click Add assertion if you also want cross-field CEL rules on top of the schema match.

Validibot parses the schema at save time, so a malformed schema fails fast — you'll see the error inline rather than on the next run.

What the validator reports¶

A JSON Schema validation produces one finding per failing constraint. Each finding tells you:

• Where the failure is (a JSON Pointer like /items/3/price),
• Which rule failed (e.g. type, required, pattern, enum),
• What was expected vs. what was found.

A submission with five bad fields produces five findings, not one. That means the submitter can fix all of them in one pass rather than playing whack-a-mole.

Schema + CEL together¶

A JSON Schema is great at "the field must exist and be a positive number." It's verbose and awkward at "if the order is for international shipping, the country code must be in the customs allow list." Validibot handles the second case by letting you add CEL step assertions on top of the schema:

# Conditional rule, expressed in CEL
p.shipping.international == false || p.shipping.country in ["AU", "NZ", "GB", "US"]

Both kinds of rule run, and findings from each appear side by side in the same report.

File types¶

JSON Schema validator accepts JSON. Make sure JSON is enabled in the workflow's allowed file types, or the validator won't be selectable on the step.

Tips¶

• Use $ref and shared definitions. If you have repeated sub-shapes (an address, a money amount), define them once under $defs and $ref them — your schema stays readable.
• Generate a starting schema from a sample. Several tools can infer a JSON Schema from an example payload; treat the output as a starting point and tighten constraints (required, enums, ranges) by hand.
• Pin the draft. Set "$schema" explicitly so future Validibot updates can't surprise you with a different draft.
• Combine with Basic for behaviour. Schemas describe shape; CEL describes behaviour. Use both.
• The schema is just a file. You can keep the schema in a Git repo and import a new version into Validibot when it changes — no bespoke deploy pipeline needed.

Where to next¶

• CEL Expressions — for step assertions on top of the schema check.
• Basic Validator — for cross-field rules better expressed as CEL.
• Validators Overview — pick the right validator for other file types.