# JSON Schema validate

JSON Schema Validate checks that a runtime value has the expected JSON structure before the workflow uses it. Place it after an Agent, webhook, HTTP Request, Database Query, Transform, or any node whose output may be incomplete or malformed.

The node uses a safe, deterministic JSON Schema subset. It does not call an AI model and does not modify valid data.

## Typical flow

```text
Database Query or API
  ↓
JSON Schema Validate
  ├── valid → normal downstream nodes
  └── invalid → stop, continue, or error branch
```

The validator must be connected to the node that produces the data. A node placed on the canvas without an incoming edge is not executed as part of that path.

## Configuration

| Field | Purpose |
| --- | --- |
| **Input field** | Context path containing the value to validate. Default: `last_output`. |
| **JSON Schema** | Schema object describing the permitted value. The editor accepts valid JSON. |
| **On invalid** | `Follow error branch`, `Stop this path`, or `Continue`. |
| **Max errors** | Maximum number of validation messages returned, from 1 to 100. Default: 20. |

### Visual schema builder

Click **Build schema visually** to define an object without writing JSON:

- add, rename, or remove properties;
- choose String, Number, Boolean, Enum, Object, or Array;
- mark each property as required or optional;
- add nested fields for objects and arrays of objects;
- choose whether undeclared fields are accepted;
- switch to the advanced JSON editor whenever you need constraints such as `pattern`, `minimum`, or `maxItems`.

The builder generates the JSON Schema automatically and remains available in both JSON Schema Validate and Output Parser's JSON Schema mode.

### What does additionalProperties mean?

`"additionalProperties": false` rejects keys that are not listed in `properties`. If the schema declares only `name` and `email`, a payload containing `phone` is invalid. Enable **Allow additional fields** in the visual builder—or use `true`—when extra keys should be accepted.

## Input field examples

| Path | Value selected |
| --- | --- |
| `last_output` | Parsed output of the immediately previous node |
| `input` | Initial workflow input |
| `input.customer` | A nested field of the initial input |
| `event.body` | Webhook or trigger body |
| `state.customer` | Value created by Set state |
| `database_query.rows` | Rows returned by the most recent Database Query |
| `outputs.node-id.parsed` | Structured output archived for a named node |

When `last_output` contains JSON text, the node parses it before validation. When the previous node already produced structured data, that parsed value is used directly.

## Supported schema keywords

The runtime currently supports:

| Keyword | Applies to | Example |
| --- | --- | --- |
| `type` | All values | `"object"`, `"array"`, `"string"`, `"integer"`, `"number"`, `"boolean"`, `"null"` |
| Type array | All values | `{"type":["string","null"]}` |
| `properties` | Objects | Defines child fields |
| `required` | Objects | Lists mandatory fields |
| `additionalProperties: false` | Objects | Rejects undeclared fields |
| `items` | Arrays | Validates each array element |
| `minItems`, `maxItems` | Arrays | Restricts array length |
| `enum` | All values | Restricts values to an allowed list |
| `minLength`, `maxLength` | Strings | Restricts text length |
| `pattern` | Strings | Applies a regular expression |
| `minimum`, `maximum` | Numbers | Restricts numeric range |

Keywords such as `$ref`, `oneOf`, `anyOf`, `allOf`, `const`, `format`, `uniqueItems`, and conditional schemas are not enforced by this node. Use the supported keywords or a Transform for advanced validation.

## Simple object example

Payload:

```json
{
  "name": "Awa Ndiaye",
  "email": "awa@example.com",
  "age": 28,
  "status": "active"
}
```

Schema:

```json
{
  "type": "object",
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "email": {
      "type": "string",
      "pattern": "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$"
    },
    "age": { "type": "integer", "minimum": 18 },
    "status": { "type": "string", "enum": ["active", "inactive"] }
  },
  "required": ["name", "email", "status"],
  "additionalProperties": false
}
```

`required` controls whether a field must exist. A field declared in `properties` but omitted from `required` is optional.

## Array example

To validate `database_query.rows` directly:

```json
{
  "type": "array",
  "minItems": 1,
  "maxItems": 100,
  "items": {
    "type": "object",
    "properties": {
      "id": { "type": "integer" },
      "name": { "type": "string", "minLength": 1 },
      "status": { "type": "string", "enum": ["active", "inactive"] }
    },
    "required": ["id", "name", "status"],
    "additionalProperties": false
  }
}
```

## Complete Database Query output example

With **Input field** set to `last_output`, Database Query provides an envelope. Validate it with:

```json
{
  "type": "object",
  "properties": {
    "database_type": { "type": "string", "enum": ["postgres"] },
    "row_count": { "type": "integer", "minimum": 0 },
    "fields": {
      "type": "array",
      "items": { "type": "string" }
    },
    "rows": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string", "minLength": 1 },
          "email": { "type": "string" },
          "status": { "type": "string" },
          "order_count": { "type": "integer", "minimum": 0 },
          "total_amount": { "type": ["string", "number"] }
        },
        "required": ["id", "name", "email", "status", "order_count", "total_amount"],
        "additionalProperties": false
      }
    },
    "truncated": { "type": "boolean" },
    "max_rows": { "type": "integer", "minimum": 1 }
  },
  "required": ["database_type", "row_count", "fields", "rows", "truncated", "max_rows"],
  "additionalProperties": false
}
```

Decimal database values may be serialized as strings, which is why `total_amount` accepts both `string` and `number`.

## Behaviour on invalid data

### Follow error branch

Marks the node as failed and follows an outgoing error edge. Connect the node's error output to a notification, fallback, or repair path. Without a connected error edge, that path stops.

### Stop this path

Stops the current path immediately. Independent workflow branches may continue.

### Continue

Keeps following the normal output even though validation failed. The error and validation details remain available in the trace and structured output. Use this mode for initial testing or when a downstream node handles the error explicitly.

## Runtime output

The structured validation result has this shape:

```json
{
  "valid": true,
  "errors": [],
  "data": {},
  "input_path": "last_output"
}
```

On success:

- `last_output` remains the validated payload;
- `last_output_parsed` contains the validation result above;
- the result is also available as `schema_validation`;
- named node output can be read with `{outputs.<node_id>.parsed.data}`.

On failure:

- `last_output` becomes a readable `JSON Schema Validate Error` message;
- `last_output_parsed.valid` is `false`;
- `last_output_parsed.errors` lists paths such as `$.rows[0].email`;
- `last_output_parsed.data` retains the rejected payload for diagnosis or repair.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| Node never appears in the trace | It is not connected to the producing path | Add an incoming and outgoing edge |
| Root says “expected object, got list” | The selected value is an array | Use `type: array` or select the correct object path |
| Read/validation input is empty | Input field points to a missing context path | Inspect the previous node output and correct Input field |
| Every row reports additional fields | `additionalProperties: false` is stricter than the real payload | Add the fields to `properties` or remove that constraint |
| Email `format` is ignored | `format` is not part of the supported subset | Use a `pattern` expression |
| A valid decimal fails as number | Database driver serialized it as text | Accept `["string", "number"]` or convert it in Transform |
| Only some errors are shown | Max errors truncated the list | Increase Max errors, up to 100 |

## Example workflow

Use the workflow card below to create a runnable example. Set State loads a customer object, then JSON Schema validates its required fields.

---

*Source: https://agentbuilder.systalink.sn/docs/node-json-schema-validate — human documentation.*
*Other language: [/docs-md/fr/node-json-schema-validate.md](/docs-md/fr/node-json-schema-validate.md).*
*Machine-readable index: [/llms.txt](/llms.txt).*