Skip to main content

Input/Output Schema Validation

Available since
  • v3.3.85 and later
  • v4.0.11 and later

In Orkes Conductor, you can create schemas to define and enforce the payload structure of workflow or task inputs/outputs. Once created, schemas can be added to workflow or task definitions:

  • A workflow-level schema specifies what workflow inputs must be supplied.
  • A task-level schema specifies the inputs/outputs that must be wired to/from the task. The task-level schema can be general across workflows (specified in the task definition) or unique to a specific workflow (specified in the task configuration).

The schema is enforced at runtime. The workflow or task will fail if the inputs/outputs do not pass the validation. This behavior is the main distinction between a task-level schema versus non-enforceable guides like the input keys, output keys, and input templates in a task definition.

Schema formats

Currently, schemas can be defined in the JSON Schema format. Like workflows, schemas can be versioned.

Example

{
"createTime": 1727378396701,
"updateTime": 1727378396701,
"createdBy": "user@example.com",
"updatedBy": "user@example.com",
"name": "itemSchema",
"version": 1,
"type": "JSON", // set schema type as JSON Schema
"data": { // include the JSON Schema parameters here
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://example.com/product.schema.json",
"type": "object",
"properties": {
"productId": {
"description": "The unique identifier for a product",
"type": "integer"
},
"productName": {
"description": "Name of the product",
"type": "string"
}
},
"required": [
"productId"
]
}
}

Using schemas

To enforce validation for input/output payloads, schemas can be added to:

  • A workflow definition—Enforce workflow inputs/outputs.
  • A task definition—Enforce task inputs/outputs for all instances of the task.
  • A task configuration—Enforce task inputs/outputs for a specific workflow.

Here is an overview of using schemas in Conductor workflows:

  1. Define a schema for a task’s or workflow’s inputs/outputs.
  2. Add the schema in a workflow definition, task definition, or task configuration.

Step 1: Define a schema

To define a schema:

  1. Log in to your Orkes Conductor cluster.
  2. Go to Definitions > Schemas.
  3. Select (+) New schema on the top right. A schema editor opens.
  4. Add your schema definition in the data object. Make sure to fill out at least the $schema, $id, type, and properties parameters as outlined in the JSON Schema.

Learn more about creating a JSON Schema.

Step 2: Add schema to workflow or task

If the version is unspecified, the latest schema version will be used.

To add a schema:

  1. Go to Definitions > Task.
  2. Select a task definition that you want to add a schema to.
  3. In the Schema section, select a schema to use as an Input Schema or Output Schema.
  4. Select a Version for the schema.
  5. Switch on the Enforce schema toggle.
  6. Select Save in the top right.

Screenshot of adding a schema to a task definition.

// task definition

{
...
"inputSchema": {
"name": "itemSchema",
"version": 1,
"type": "JSON"
},
"outputSchema": {
"name": "outputSchema",
"type": "JSON"
}
"enforceSchema": true
}

Once the schema is added, modify your workflow or task inputs/outputs to match the schema.

Editing schemas

Schemas can be edited in the Definitions > Schema tab or directly from where they are added to the workflow definition itself.

Since schemas can be reused for multiple workflows or tasks, you are encouraged to save changes to an existing schema as a new version or as a new schema entirely.

Workflow behavior with schemas

If a workflow does not pass its schema validation, it will not be allowed to execute.

Screenshot of execution failure due to invalid inputs.

If a task does not pass its schema validation, it will fail with a terminal error.

Screenshot of task failure due to invalid inputs or outputs.

Supported tasks

Schema validation is currently supported for the following task types: