Input/Output Schema Validation
- 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.
// 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.
// 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.
// 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.
If a task does not pass its schema validation, it will fail with a terminal error.
Supported tasks
Schema validation is currently supported for the following task types:
- Worker (Simple)
- Event
- HTTP
- HTTP Poll
- Inline
- JSON JQ Transform
- Business Rule
- Wait For Webhook
- JDBC
- Update Secret
- Get Signed JWT
- Update Task
- Opsgenie
- Query Processor
- LLM Text Complete
- LLM Generate Embeddings
- LLM Get Embeddings
- LLM Store Embeddings
- LLM Search Index
- LLM Index Document
- Get Document
- LLM Index Text
- LLM Chat Complete