Conductor Schemas

This directory contains JSON Schema definitions for the core data models used in Conductor workflow orchestration.

Overview

JSON Schemas provide a standardized way to describe the structure, validation rules, and documentation for Conductor's data models. These schemas can be used for:

• Validation: Validate workflow and task definitions before submitting them to Conductor
• Documentation: Auto-generate API documentation and client libraries
• IDE Support: Enable autocomplete and validation in editors that support JSON Schema
• Code Generation: Generate strongly-typed client code in various programming languages
• Contract Testing: Ensure API responses conform to expected formats

Schema Files

WorkflowDef.json

Purpose: Defines the structure of a workflow definition (template/blueprint).

Key Features:

• Workflow metadata (name, version, description, owner)
• List of tasks that comprise the workflow
• Input/output parameters and templates
• Timeout and retry policies
• Rate limiting and caching configurations
• Schema enforcement for input/output validation

Important Details:

• Contains a recursive WorkflowTask definition that supports complex workflow patterns:
  • Decision tasks: Branch based on conditions (decisionCases, defaultCase)
  • Fork-Join tasks: Execute tasks in parallel (forkTasks)
  • Do-While tasks: Loop over tasks (loopOver, loopCondition)
  • Sub-workflow tasks: Embed entire workflows (subWorkflowParam)
• The recursive nature allows unlimited nesting depth for complex workflow patterns

Use Case: Use this schema when creating or validating workflow definitions before registering them with Conductor.

TaskDef.json

Purpose: Defines the structure of a task definition (reusable task template).

Key Features:

• Task metadata (name, description, owner)
• Retry configuration (count, delay, logic type)
• Timeout policies and durations
• Rate limiting settings
• Input/output schema validation
• Concurrency controls

Important Details:

• Task definitions are registered separately and can be reused across multiple workflows
• Supports three retry strategies: FIXED, EXPONENTIAL_BACKOFF, LINEAR_BACKOFF
• Timeout policies determine workflow behavior: RETRY, TIME_OUT_WF, ALERT_ONLY

Use Case: Use this schema when creating or validating task definitions that will be referenced by workflows.

Workflow.json

Purpose: Represents a runtime workflow instance (actual execution).

Key Features:

• Current execution status (RUNNING, COMPLETED, FAILED, etc.)
• List of task instances that have been scheduled or executed
• Input/output data for the workflow execution
• Timing information (start, end, update times)
• Parent/child workflow relationships
• Workflow variables and correlation IDs

Important Details:

• Contains a recursive history field that stores previous executions for workflow versioning and auditing
• References the WorkflowDef that defines the workflow structure
• Each workflow has a unique workflowId
• Priority ranges from 0-99 (higher = more priority)
• External payload storage paths for large inputs/outputs

Use Case: Use this schema when querying workflow execution status or validating workflow runtime data.

Task.json

Purpose: Represents a runtime task instance (actual task execution).

Key Features:

• Current task status with detailed state information
• Input/output data for the task execution
• Worker information (workerId, domain)
• Retry and poll counts
• Timing data (scheduled, start, end, update times)
• Sub-workflow references for SUB_WORKFLOW tasks

Important Details:

• Task status enum includes:
  • Running states: IN_PROGRESS, SCHEDULED
  • Success states: COMPLETED, COMPLETED_WITH_ERRORS, SKIPPED
  • Failure states: FAILED, FAILED_WITH_TERMINAL_ERROR, TIMED_OUT, CANCELED
• Contains reference to the WorkflowTask template definition
• For loop tasks: iteration field tracks the current iteration number
• executionMetadata provides detailed timing and worker context information

Use Case: Use this schema when querying individual task execution details or validating task runtime data.

Common Patterns

Inheritance Hierarchy

All definition schemas (WorkflowDef, TaskDef, SchemaDef) inherit audit fields from the Auditable base class:

• ownerApp: Application that owns this definition
• createTime: Timestamp when created (milliseconds since epoch)
• updateTime: Timestamp when last updated
• createdBy: User who created the definition
• updatedBy: User who last updated the definition

Additionally, definitions implement the Metadata interface requiring:

• name: Unique identifier
• version: Version number

Recursive Structures

The schemas correctly model two important recursive relationships in Conductor:

WorkflowTask recursion: Tasks can contain nested tasks for control flow

WorkflowTask
├── decisionCases: Map<String, List<WorkflowTask>>
├── defaultCase: List<WorkflowTask>
├── forkTasks: List<List<WorkflowTask>>
└── loopOver: List<WorkflowTask>

Schema Validation

Schemas are defined to support JSON Schema validation using the $ref keyword. Both internal references (#/definitions/...) and external references are supported.

Enumerations

All enum types from the Java code are represented as string enums with allowed values explicitly listed:

• Workflow status: RUNNING, COMPLETED, FAILED, TIMED_OUT, TERMINATED, PAUSED
• Task status: IN_PROGRESS, CANCELED, FAILED, FAILED_WITH_TERMINAL_ERROR, COMPLETED, COMPLETED_WITH_ERRORS, SCHEDULED, TIMED_OUT, SKIPPED
• Timeout policies: RETRY, TIME_OUT_WF, ALERT_ONLY
• Retry logic: FIXED, EXPONENTIAL_BACKOFF, LINEAR_BACKOFF
• Schema types: JSON, AVRO, PROTOBUF

Usage Examples

Validating a Workflow Definition

# Using ajv-cli
ajv validate -s schemas/WorkflowDef.json -d my-workflow.json

# Using Python with jsonschema
python -c "
import json
import jsonschema

with open('schemas/WorkflowDef.json') as f:
    schema = json.load(f)

with open('my-workflow.json') as f:
    workflow = json.load(f)

jsonschema.validate(workflow, schema)
print('Valid workflow definition!')
"

IDE Integration

Most modern IDEs support JSON Schema for validation and autocomplete:

VS Code: Add this to the top of your JSON file:

{
  "$schema": "./schemas/WorkflowDef.json",
  "name": "my-workflow",
  ...
}

IntelliJ IDEA: Configure JSON Schema mappings in Settings → Languages & Frameworks → Schemas and DTDs → JSON Schema Mappings

Schema Specifications

All schemas conform to JSON Schema Draft 07 specification (http://json-schema.org/draft-07/schema#).

Key validation features used:

• type: Data type constraints
• required: Required fields
• minimum/maximum: Numeric bounds
• minLength/maxLength: String length constraints
• minItems: Array minimum length
• pattern: Regular expression matching
• enum: Allowed values
• format: Data format hints (email, int64, etc.)
• default: Default values
• additionalProperties: Allow/disallow extra fields
• $ref: Schema composition and reuse

Relationship to Java Models

These schemas are derived from the Java model classes in the Conductor codebase:

The schemas accurately reflect:

• All fields including inherited fields from Auditable and Metadata
• Jackson annotations for serialization behavior
• Jakarta validation constraints
• Protobuf field mappings

Version

Current schema version: 1.0 Based on Conductor version: 3.x Last updated: October 2025