JSON ValidateJsonSchema

JSON ValidateJsonSchema

Certified

Validate JSON data against a JSON Schema

Validates a JSON payload against a JSON Schema, given inline or fetched from a Confluent-compatible Schema Registry such as Karapace.

The $schema keyword of the schema selects the draft; when it is absent, defaultDialect is used. Draft-04, draft-06 and draft-07 check format values. Draft 2019-09 and draft 2020-12, the default, treat format as an annotation and do not check it, as the specification requires; set $schema or defaultDialect to an earlier draft to enforce formats.

With draft-04 the validator mirrors java-json-tools/json-schema-validator: the same set of checked format values (date-time, email, hostname, ipv4, ipv6, regex, uri, uuid, json-pointer, uri-template, base64, md5, sha1, sha256, sha512, mac), ECMA-262 regular expressions, and unknown keywords ignored. Keywords that need custom validator code are therefore not enforced.

Remote $ref URLs are never fetched. The payload is read as a single JSON document; JSONL files are not validated record by record.

yaml
type: io.kestra.plugin.serdes.json.ValidateJsonSchema

Validate a payload against an inline JSON Schema and fail the task when it does not match.

yaml
id: validate_json_inline
namespace: company.team

inputs:
  - id: payload
    type: JSON
    defaults: '{"id": 1, "email": "ada@example.com"}'

tasks:
  - id: validate
    type: io.kestra.plugin.serdes.json.ValidateJsonSchema
    from: "{{ inputs.payload }}"
    schema: |
      {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "required": ["id", "email"],
        "properties": {
          "id": {"type": "integer"},
          "email": {"type": "string", "format": "email"}
        }
      }

Validate a stored file against a namespace file schema, using draft-04 when the schema has no $schema.

yaml
id: validate_json_namespace_file
namespace: company.team

tasks:
  - id: download
    type: io.kestra.plugin.core.http.Download
    uri: https://example.com/data/orders.json

  - id: validate
    type: io.kestra.plugin.serdes.json.ValidateJsonSchema
    from: "{{ outputs.download.uri }}"
    schema: "{{ read('schemas/order.json') }}"
    defaultDialect: DRAFT_4

Validate against a schema stored in a Karapace registry and branch on the result instead of failing.

yaml
id: validate_json_registry
namespace: company.team

tasks:
  - id: fetch_order
    type: io.kestra.plugin.core.http.Request
    uri: https://example.com/api/orders/42

  - id: validate
    type: io.kestra.plugin.serdes.json.ValidateJsonSchema
    from: "{{ outputs.fetch_order.body }}"
    failOnInvalid: false
    registry:
      url: https://my-karapace.aivencloud.com:12345
      subject: orders-value
      subjectVersion: latest
      options:
        auth:
          type: BASIC
          username: "{{ secret('REGISTRY_USERNAME') }}"
          password: "{{ secret('REGISTRY_PASSWORD') }}"

  - id: if_invalid
    type: io.kestra.plugin.core.flow.If
    condition: "{{ outputs.validate.valid == false }}"
    then:
      - id: report
        type: io.kestra.plugin.core.log.Log
        message: "Invalid order: {{ outputs.validate.errors }}"
Installation

Our standard Docker images already include this plugin. If you use a -slim image or another setup, install it with the following command: 

kestractl plugins get io.kestra.plugin:plugin-serdes --compatible-for $KESTRA_VERSION

For kestractl, use your Kestra version with --compatible-for, or specify an exact plugin version.

For Kestra CLI, replace LATEST with a specific version or version range to pin the plugin version.

Properties

JSON data to validate

One of: a string containing JSON text, a kestra:// internal storage URI of a JSON file (read as UTF-8), or an object, array or scalar value, which is serialized to JSON before validation.

Assets this task consumes as inputs or produces as outputs, for lineage tracking and the asset graph (Enterprise Edition). A flow declaring this property on a task is rejected in the open-source edition.

Definitions
assetFailureBehaviorstring
Possible Values
IGNOREFAILWARN

Asset failure behavior

Behavior applied to the task state when a declared asset fails to render, emit, or be persisted (e.g. a lock conflict): FAIL escalates it to FAILED, WARN (default) warns it if it would otherwise succeed, IGNORE leaves the state untouched.

enableAutobooleanstring

Whether to auto-register assets referenced dynamically at runtime that are not statically declared in inputs or outputs.

inputsarray

The assets consumed as inputs.

id*string
Min length1
typestring
outputs

The assets produced as outputs.

id*string
Min length1
Max length150
type*object
descriptionstring
displayNamestring
metadataobject
Default{}
namespacestring
Min length1
Max length150
id*string
Min length1
Max length150
type*object
descriptionstring
displayNamestring
metadataobject
Default{}
namespacestring
Min length1
Max length150
id*string
Min length1
Max length150
type*object
descriptionstring
displayNamestring
metadataobject
Default{}
namespacestring
Min length1
Max length150
id*string
Min length1
Max length150
type*object
descriptionstring
displayNamestring
metadataobject
Default{}
namespacestring
Min length1
Max length150
id*string
Min length1
Max length150
type*object
descriptionstring
displayNamestring
metadataobject
Default{}
namespacestring
Min length1
Max length150
id*string
Min length1
Max length150
type*string
Min length1

Custom asset type

descriptionstring
displayNamestring
metadataobject
Default{}
namespacestring
Min length1
Max length150
DefaultDRAFT_2020_12
Possible Values
DRAFT_4DRAFT_6DRAFT_7DRAFT_2019_09DRAFT_2020_12

Default dialect

Draft used when the schema has no $schema keyword. One of DRAFT_4, DRAFT_6, DRAFT_7, DRAFT_2019_09 or DRAFT_2020_12. Defaults to DRAFT_2020_12, where format is annotation-only as the specification requires; set DRAFT_4 to match java-json-tools/json-schema-validator, which checks formats.

Defaulttrue

Fail on invalid data

When true (default), the task fails if the data does not match the schema. When false, the task succeeds with valid: false and the list of errors.

Schema Registry

Fetch the schema from a Confluent-compatible Schema Registry. Set exactly one of schema or registry.

Definitions

Fetches a JSON Schema from a Confluent-compatible Schema Registry such as Karapace. Set either subject (with an optional subjectVersion) or id. Only registered schemas of type JSON without references are supported.

idintegerstring

Global schema ID

Registry-wide schema ID. Mutually exclusive with subject.

options

HTTP options

Authentication (basic or bearer), SSL, proxy and timeout settings used to call the registry.

allowFailedbooleanstring
Defaultfalse

If true, allow a failed response code (response code >= 400)

allowedResponseCodesarray
SubTypeinteger

List of response code allowed for this request

auth

The authentication to use.

type*object
passwordstring

The password for HTTP basic authentication.

usernamestring

The username for HTTP basic authentication.

type*object
tokenstring

The token for bearer token authentication.

type*object
passwordstring

The password for HTTP Digest authentication.

usernamestring

The username for HTTP Digest authentication.

defaultCharsetstring
DefaultUTF-8

The default charset for the request.

enabledTcpExtendedKeepAlivebooleanstring
Defaulttrue

Whether to enable TCP Keep-Alive extended socket options (TCP_KEEPIDLE, TCP_KEEPINTERVAL, TCP_KEEPCOUNT).

Set to false when running on Windows workers, as these extended socket options are not supported by the Windows JDK and will cause connection failures.

followRedirectsbooleanstring
Defaulttrue

Whether redirects should be followed automatically.

logsarray
SubTypestring
Possible Values
REQUEST_HEADERSREQUEST_BODYRESPONSE_HEADERSRESPONSE_BODY

The enabled log.

proxy

The proxy configuration.

addressstring

The address of the proxy server.

passwordstring

The password for proxy authentication.

portintegerstring

The port of the proxy server.

typestring
DefaultDIRECT
Possible Values
DIRECTHTTPSOCKS

The type of proxy to use.

usernamestring

The username for proxy authentication.

retry

Retry strategy for HTTP requests.

retry is disabled by default.

Retry with a fixed delay between attempts.

interval*string
Formatduration
type*object
behaviorstring
DefaultRETRY_FAILED_TASK
Possible Values
RETRY_FAILED_TASKCREATE_NEW_EXECUTION
maxAttemptsinteger
Minimum>= 1
maxDurationstring
Formatduration
warningOnRetryboolean
Defaultfalse

Retry with exponentially increasing delays between attempts.

interval*string
Formatduration
maxInterval*string
Formatduration
type*object
behaviorstring
DefaultRETRY_FAILED_TASK
Possible Values
RETRY_FAILED_TASKCREATE_NEW_EXECUTION
delayFactornumber
maxAttemptsinteger
Minimum>= 1
maxDurationstring
Formatduration
warningOnRetryboolean
Defaultfalse

Retry with a random delay within a configurable range between attempts.

maxInterval*string
Formatduration
minInterval*string
Formatduration
type*object
behaviorstring
DefaultRETRY_FAILED_TASK
Possible Values
RETRY_FAILED_TASKCREATE_NEW_EXECUTION
maxAttemptsinteger
Minimum>= 1
maxDurationstring
Formatduration
warningOnRetryboolean
Defaultfalse
retryOnStatusCodesarray
SubTypeinteger
Default[502,503,504]

HTTP status codes that should be retried.

Used for idempotent methods (GET, HEAD) without their own entry in retryOnStatusCodesByMethod. Non-idempotent methods are never retried on a status code unless listed in retryOnStatusCodesByMethod. Defaults to 502, 503 and 504 for idempotent methods (GET, HEAD) only.

retryOnStatusCodesByMethodobject
SubTypearray

Per-HTTP-method overrides for which status codes should be retried.

Keys are HTTP methods (e.g. GET, POST). A method with no entry here falls back to retryOnStatusCodes. This lets a caller retry more broadly for safe, read-only methods (for example, every 5xx and a 429 for GET/HEAD) while keeping a narrower list for methods that write, where retrying a request that may have already been processed by the origin risks duplicating the effect. Example: {GET: [429, 500, 502, 503, 504], HEAD: [429, 500, 502, 503, 504]}.

retryableTransportFailureMethodsarray
SubTypestring
Default["GET","HEAD"]

HTTP methods for which any transport-level failure may be retried.

A transport-level failure is a connection or timeout error rather than an HTTP response (e.g. a read timeout or a connection reset mid-request). For a method listed here, any such failure is retried. Defaults to GET and HEAD HTTP methods.

ssl

The SSL request options

insecureTrustAllCertificatesbooleanstring

Whether to disable checking of the remote SSL certificate.

Only applies if no trust store is configured. Note: This makes the SSL connection insecure and should only be used for testing. If you are using a self-signed certificate, set up a trust store instead.

timeout

The timeout configuration.

connectTimeoutstring

The time allowed to establish a connection to the server before failing.

readIdleTimeoutstring
DefaultPT5M

The time allowed for a read connection to remain idle before closing it.

subjectstring

Subject

Subject holding the schema. Required unless id is set.

subjectVersionstring

Subject version

Version of the subject: an integer or latest, which is the default. Ignored when id is set.

urlstring

Registry URL

Base URL of the registry, for example https://my-registry.example.com: 12345. A path prefix is allowed.

Inline JSON Schema

The JSON Schema as text. Use {{ read('path/to/schema.json') }} to load a namespace file. Set exactly one of schema or registry.

Validation errors

Empty when valid. Limited to the first 100 errors; the errors metric holds the total.

Definitions
instanceLocationstring

JSON Pointer to the offending value in the data

Empty for the document root.

keywordstring

Schema keyword that failed

For example required or type.

messagestring

Human-readable error message

schemaLocationstring

Location of the failing keyword in the schema

Registry schema ID

Only set when the schema came from a registry.

Registry subject version

Only set when the schema came from a registry subject.

Defaultfalse

Whether the data matches the schema

Number of validation errors found

More Plugins in this Category

Core Plugins and tasks
Core Plugins and tasks

Tasks that provide Kestra's built-in orchestration, I/O, and observability capabilities.

Core

109 tasks

2141 blueprints

Firecrawl
Firecrawl

Tasks that scrape and crawl websites into clean, LLM-ready content with Firecrawl.

Data

2 tasks