Skip to content

feat: YAML workflow definition format (parity with existing JSON support) #2

@JerrettDavis

Description

@JerrettDavis

Overview

WorkflowFramework ships JSON workflow configuration support (JsonWorkflowDefinitionLoader). The README notes "YAML coming soon." This issue tracks delivering YAML parity.

Context

JD.AI (the primary consumer of WorkflowFramework) uses YAML extensively for policy documents (PolicyDocument), agent definitions (.agent.yaml, see JerrettDavis/JD.AI#201), and tool loadouts (.loadout.yaml, see JerrettDavis/JD.AI#214). A consistent YAML-first authoring experience across all JD.AI configuration is the goal. Having workflow definitions also in YAML eliminates the JSON outlier.

Goal

Implement YamlWorkflowDefinitionLoader with full feature parity to JsonWorkflowDefinitionLoader:

# my-workflow.workflow.yaml
name: OrderProcessing
version: "2.0"
description: Process customer orders end-to-end

steps:
  - name: ValidateOrder
    type: step
    class: ValidateOrder

  - name: PaymentDecision
    type: conditional
    condition: "ctx.Data.IsValid"
    then:
      - name: ChargePayment
        type: step
        class: ChargePayment
    else:
      - name: RejectOrder
        type: step
        class: RejectOrder

  - name: FulfillmentJobs
    type: parallel
    steps:
      - name: SendEmail
        type: step
        class: SendEmail
      - name: UpdateInventory
        type: step
        class: UpdateInventory

  - name: HumanReview
    type: approval
    message: "Order {{ ctx.Data.OrderId }} requires manager sign-off"
    required_approvers: 1
    timeout_minutes: 1440

  - name: Complete
    type: step
    class: CompleteOrder

Scope

All step types supported in JSON should be supported in YAML:

  • step — standard step by class name
  • conditional — If/Then/Else
  • parallel — concurrent steps
  • foreach / while / dowhile / retry — loops
  • try / catch / finally — error handling
  • subworkflow — nested workflow by name
  • approval — human approval gate
  • saga — compensation-enabled group

Acceptance Criteria

  • YamlWorkflowDefinitionLoader implementing same interface as JsonWorkflowDefinitionLoader
  • Shared WorkflowDefinition object model between JSON and YAML loaders
  • All step types: step, conditional, parallel, foreach, while, dowhile, retry, try/catch/finally, subworkflow, approval, saga
  • Step attributes expressible in YAML (timeout, retry, name, order)
  • WorkflowFramework.Extensions.Configuration extended with AddYamlWorkflowLoader()
  • Round-trip: load from YAML → serialize to JSON → reload from JSON → same execution behavior
  • Schema validation: clear error messages for invalid YAML structure
  • Tests: all step types via YAML, validation errors, round-trip consistency
  • WorkflowFramework.Serialization updated to support YAML format

Metadata

Metadata

Labels

enhancementNew feature or request

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions