JSON Validator

JSON_VALIDATOR is a Component type for declarative validation. It contains exactly one element whose source is a JSON validator schema. Use it directly in Sandbox validation, attach it to an Endpoint as a reusable guard, or use an inline copy under an Endpoint’s options.guard when reuse is unnecessary.

Where validation runs

For an Endpoint, validation happens after method/path matching and before the target Component is resolved. The value being validated has this shape:

{
  "query": { "notify": "true" },
  "headers": { "content-type": "application/json" },
  "parameters": { "orderId": "order-123" },
  "body": { "channel": "email" }
}

Do not validate the raw transport request in application code when a boundary rule is known in advance. A guard produces a controlled client error before business logic, Storage access, database writes, or integration calls begin.

Schema shape

For an Endpoint, the root is a ValidatorSchema object whose schema is an object with objectSchema entries. Use profile: "strict" for new contracts. Schemas without a profile preserve legacy behavior; review accepted and rejected values before changing an existing profile.

{
  "profile": "strict",
  "additionalProperties": "reject",
  "schema": {
    "type": "object",
    "objectSchema": [
      {
        "property": "body",
        "schema": {
          "type": "object",
          "objectSchema": [
            {
              "property": "currency",
              "schema": {
                "type": "string",
                "required": true,
                "enum": [
                  "PLN",
                  "EUR",
                  "USD"
                ]
              }
            },
            {
              "property": "amount",
              "schema": {
                "type": "number",
                "required": true,
                "min": 0.01,
                "max": 100000
              }
            },
            {
              "property": "labels",
              "schema": {
                "type": "array",
                "arraySchema": {
                  "type": "string",
                  "max": 32
                }
              }
            }
          ],
          "required": true
        }
      },
      {
        "property": "parameters",
        "schema": {
          "type": "object",
          "objectSchema": [
            {
              "property": "orderId",
              "schema": {
                "type": "string",
                "required": true,
                "min": 1,
                "max": 64
              }
            }
          ]
        }
      },
      {
        "property": "query",
        "schema": {
          "type": "object",
          "additionalProperties": "allow"
        }
      },
      {
        "property": "headers",
        "schema": {
          "type": "object",
          "additionalProperties": "allow"
        }
      }
    ]
  }
}

At the Endpoint boundary, root properties are body, query, headers, and parameters. query, headers, and parameters must be an object (or any); body may use any supported type. A route without dynamic segments normally receives an empty parameters object.

Property rules

Field	Applies to	Meaning
`type`	every property	`string`, `number`, `integer`, `boolean`, `object`, `array`, `date`, or `any`.
`required`	every property	Requires presence; `false`, `0` and an empty string are still present values.
`nullable`	every property	Controls whether an explicitly supplied `null` is allowed, separately from presence.
`empty`	string, array	`allow` or `reject` for empty strings and arrays.
`enum`, `const`	every property	A finite set of exact JSON values, or one exact value. These do not make a missing property required.
`min`, `max`	string, number, integer, array	Inclusive length, numeric range or item-count bounds.
`integer`, `finite`, `safeInteger`	number	Integer, finite-number or safe-integer constraints; `type: "integer"` also requires an integer.
`exclusiveMin`, `exclusiveMax`	number, integer	Exclusive numeric bounds.
`format`, `timezone`	date/time string	Supported formats include `date`, `time` and `date-time`; `timezone: true` requires an explicit offset for time values.
`objectSchema`, `arraySchema`	object, array	Named child-property rules, or the rule applied to each array item.
`additionalProperties`	object	`allow`, `strip` or `reject` for undeclared properties.
`regex`, `regexFlags`	string	A required text pattern and optional JavaScript regex flags. Prefer equivalent explicit rules first.

In the strict profile, numbers must be finite and null requires nullable: true. A strict date accepts a valid Date value or a supported date/date-time string; legacy date rules also accept values parsable as JavaScript dates. any skips type constraints, but presence, nullability and resource limits still apply. Default string length is measured in UTF-16 code units. Validation has limits on schema size, nesting, input processing and error output. A successful example is not proof that unbounded arrays or arbitrarily complex rules will fit every execution budget.

Choose explicit rules before regex

Prefer enum for known values, const for a single value, and type, length, numeric range or supported date/time rules for their respective constraints. Add regex only when the contract requires a text pattern those rules cannot express. A simple regex can roughly double request-preparation time or more, even for small payloads. This adds CPU work and latency; it is not limited to unusually complex patterns. Measure representative requests when introducing a pattern on a frequently called Endpoint.

Requirement	Preferred rule
One of three warehouse codes	`enum: ["PL01", "PL02", "PL03"]`
Exactly one event name	`const: "order.created"`
Nonempty bounded text	`type: "string"`, `min: 1`, `max: 64`
Positive whole-number quantity	`type: "integer"`, `min: 1`
Timestamp with a timezone	`type: "string"`, `format: "date-time"`, `timezone: true`
An identifier with a required prefix and character pattern	A narrowly scoped `regex` plus a business-appropriate `max` length

The schema example above explicitly limits currencies to three codes and accepts a nonempty order identifier of up to 64 code units. If your contract requires a specific identifier pattern, retain that requirement and use a regex when necessary. Do not remove a validation constraint to gain speed. Check case sensitivity, whitespace, empty values and trailing newlines when replacing an existing regex.

Measured scale of the difference

The comparison below uses the same valid requests and the same structural rules. One field accepts exactly PL01, PL02 or PL03: one variant uses enum, the other uses regex: "^(PL01|PL02|PL03)$". Both require a string with max: 4, so a trailing newline is rejected as well. Matching and rejecting examples were checked before timing.

Request size	Explicit `enum`	One equivalent regex	Relative time
4 KiB	0.068 ms	0.180 ms	2.6×
16 KiB	0.181 ms	0.321 ms	1.8×
32 KiB	0.312 ms	0.776 ms	2.5×
64 KiB	0.545 ms	1.048 ms	1.9×
128 KiB	0.984 ms	1.977 ms	2.0×

These are median Endpoint request-preparation times from a controlled single-CPU benchmark, with 30 measured calls per variant after warmup. Requests contain arrays of records with a nested 30-field object. The measurement includes route resolution, guard validation, request-log preparation and execution-context assembly. It excludes network time, HTTP parsing, authentication, real database access and business execution. Use the table to understand scale, not as a latency guarantee or a multiplier for the entire HTTP request. The effect depends on the schema, data shape, number and length of strings, concurrency and available capacity. These Endpoint measurements are not timings for every util.validate() call.

Unknown fields

For new schemas, use additionalProperties: "allow", "strip" or "reject". A root policy supplies the default for object rules; an object’s own policy overrides it. The strict default is reject. Existing schemas retain the legacy flag behavior:

Setting	Behavior for an undeclared field
`whitelist: true`	Retains the field without an unknown-field error.
`whitelist: false`, `whitelistErrors: false`	Removes the field from the value passed onward.
`whitelist: false`, `whitelistErrors: true`	Retains the field and reports an `unexpected property found` error.

An explicit additionalProperties policy takes precedence over these legacy flags. Choose reject when an API contract must refuse unknown input; choose strip deliberately when passing only declared fields onward.

Attach a reusable validator to an Endpoint

Configure the schema Component under the Endpoint’s options. Pin componentSchemaVersion for a stable contract; omit it only when the Endpoint should deliberately follow the latest active validator version.

{
  "componentSchemaId": "1f24e4ca-2dd0-4ce0-9fd9-4c0cd76e3ab1",
  "componentSchemaElement": "requestSchema",
  "componentSchemaVersion": 7,
  "validateResponse": 422,
  "validateHideResponse": false,
  "customValidateResponse": { "message": "Payload is not valid" }
}

Use either guard or componentSchemaId as the source of a contract. A reusable schema Component improves consistency across Endpoints; an inline guard keeps a one-off contract next to its Endpoint.

`util.validate()` in low-code

For validation inside a Component, use util.validate(). It uses the same schema model but does not replace Endpoint boundary validation: the target Component has already started when it runs. Call it with await. The result contains valid, compatible string errors, structured issues (code, path, message, optional params) and the validated value. After success, use value so configured field removal is respected. Execution or capacity failures can reject the Promise; handle these separately from a normal invalid-data result.

Test matrix

Before activation, test at least:

a valid complete request;
every required field missing;
a wrong primitive type;
minimum, maximum, enum/const and, when used, regex boundaries;
missing versus null and empty values;
an invalid array item;
an unexpected property in the selected unknown-field mode;
missing, empty, and dynamic route parameter cases.

Validation errors can reflect caller input. Do not return raw errors when field names, policy details, or submitted values would disclose sensitive information. Prefer a concise customValidateResponse for public APIs.

Build applications

Low-code runtime

Low-code reference

Where validation runs

Schema shape

Property rules

Choose explicit rules before regex

Measured scale of the difference

Unknown fields

Attach a reusable validator to an Endpoint

`util.validate()` in low-code

Test matrix

​Where validation runs

​Schema shape

​Property rules

​Choose explicit rules before regex

​Measured scale of the difference

​Unknown fields

​Attach a reusable validator to an Endpoint

​util.validate() in low-code

​Test matrix

Where validation runs

Schema shape

Property rules

Choose explicit rules before regex

Measured scale of the difference

Unknown fields

Attach a reusable validator to an Endpoint

`util.validate()` in low-code

Test matrix