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:

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

Step 1: Define a schema

To define a schema:

Log in to your Orkes Conductor cluster.
Go to Definitions > Schemas.
Select (+) New schema on the top right. A schema editor opens.
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:

Task definition
Task configuration
Workflow definition

Go to Definitions > Task.
Select a task definition that you want to add a schema to.
In the Schema section, select a schema to use as an Input Schema or Output Schema.
Select a Version for the schema.
Switch on the Enforce schema toggle.
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
}

Go to Definitions > Workflow.
Select a workflow that you want to add a task-level schema to.
In the visual workflow editor, select a task.
In the Schema section, switch on the Enforce schema toggle.
Select a schema to use as an Input Schema or Output Schema.
Select a Version for the schema.
Select Save > Confirm in the top right.

Screenshot of adding a schema to a task configuration in the workflow definition.

// workflow definition

{
...
  "tasks": [
    {
      "name": "getItem",
      "taskReferenceName": "getItem_ref",
      "inputParameters": {
        "productId": 1,
        "productName": "toy"
      },
      "type": "SIMPLE",
      "taskDefinition": {
        "inputSchema": {
          "createTime": 0,
          "updateTime": 0,
          "name": "itemSchema",
          "type": "JSON"
        },
        "outputSchema": {
          "name": "outputSchema",
          "version": 1,
          "type": "JSON"
        },
        "enforceSchema": true
      }
    }
  ]
}

Go to Definitions > Workflow.
Select a workflow that you want to add a task-level schema to.
In the Schema section of the Workflow tab, switch on the Enforce schema toggle.
Select a schema to use as an Input Schema or Output Schema.
Select a Version for the schema.
Select Save > Confirm in the top right.

Screenshot of adding a schema to the workflow definition.

// workflow definition

{
...
  "inputSchema": {
    "name": "itemSchema",
    "version": 1,
    "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:

Schema formats​

Using schemas​

Step 1: Define a schema​

Step 2: Add schema to workflow or task​

Editing schemas​

Workflow behavior with schemas​

Supported tasks​