Proposal: Official Migration Tool for 0.8/0.9 to 1.0.0 Workflows

[ricardozanini]

Proposal: Official Migration Tool for 0.8/0.9 to 1.0.0 Workflows

Problem Statement

The Serverless Workflow specification has undergone a significant architectural redesign between versions 0.8/0.9 and 1.0.0. The earlier versions used a state-based model with explicit state machines and transitions, while version 1.0.0 introduces a fundamentally different task-based model with declarative task composition and implicit flow control.

This architectural shift creates a substantial migration challenge for existing users:

Current Pain Points

1. No Clear Migration Path: Users with existing 0.8/0.9 workflows have no official guidance or tooling to migrate to 1.0.0

2. Manual Migration is Time-Consuming: Converting workflows requires:

   • Deep understanding of both specification versions
   • Rewriting workflow structure from state-based to task-based model
   • Converting JsonPath expressions to jq syntax
   • Mapping different data filter semantics
   • Understanding subtle differences in error handling, authentication, and flow control

3. Error-Prone Process: Manual migration risks:

   • Incorrect semantic mappings
   • Loss of functionality
   • Subtle bugs in data transformations
   • Broken workflows that fail at runtime

4. Adoption Blocker: The migration burden may prevent users from:

   • Adopting the improved 1.0.0 specification
   • Benefiting from new features and better ergonomics
   • Staying current with the specification evolution

Example Complexity

A simple 0.8/0.9 workflow with states and transitions:

{
  "name": "order-workflow",
  "specVersion": "0.8",
  "start": "validate-order",
  "states": [
    {
      "name": "validate-order",
      "type": "operation",
      "actions": [...],
      "transition": "process-payment"
    },
    {
      "name": "process-payment",
      "type": "operation",
      "actions": [...],
      "end": true
    }
  ]
}

Requires significant restructuring to become a valid 1.0.0 workflow with tasks, document metadata, and different flow control.

Proposed Solution

Develop an official Migration Tool that automates the conversion of 0.8 and 0.9 workflow definitions to version 1.0.0.

What the Tool Should Do

1. Automatic Migration: Convert common workflow patterns automatically (target: 80%+ coverage)
2. Transparency: Generate detailed reports showing what was migrated and what needs manual review
3. Validation: Validate migrated workflows against the 1.0.0 schema
4. Guidance: Provide actionable next steps for patterns that cannot be auto-migrated

Key Features

• Support both JSON and YAML input formats
• Handle all 8 state types from 0.8/0.9 (Event, Operation, Switch, Inject, ForEach, Parallel, Sleep, Callback)
• Convert JsonPath expressions to jq syntax (best-effort)
• Map data filters to 1.0.0 input/output semantics
• Generate migration reports highlighting warnings and manual steps
• Validate output against 1.0.0 specification

Expected Outcomes

• Lower Adoption Barrier: Users can confidently migrate existing workflows
• Save Time: Automate repetitive, mechanical transformation work
• Reduce Errors: Standardized transformations minimize human error
• Educational Value: Migration reports help users understand version differences
• Community Signal: Demonstrates commitment to supporting users through major changes

Why This Matters

For Users

• Existing users can preserve their investment in 0.8/0.9 workflows
• Migration becomes hours instead of days/weeks
• Confidence that migrations follow best practices
• Clear understanding of what requires manual attention

For the Specification

• Removes major barrier to 1.0.0 adoption
• Supports healthy ecosystem growth
• Shows maturity and commitment to backward compatibility
• Helps validate that the 1.0.0 design accommodates previous use cases

For the CNCF Ecosystem

• Aligns with CNCF values of open, accessible tooling
• Demonstrates specification evolution best practices
• Encourages broader serverless workflow adoption

Scope Boundaries

In Scope

• Automated migration of common workflow patterns
• Support for both 0.8 and 0.9 source versions
• Comprehensive migration reporting
• Validation against 1.0.0 specification

Out of Scope (for initial version)

• 100% automatic migration of all edge cases (realistic target: 80%+)
• Reverse migration (1.0.0 → 0.8/0.9)
• Runtime-specific extensions or custom features
• Interactive/GUI-based migration (CLI-first approach)

Success Criteria

1. Coverage: Successfully migrate 80%+ of common workflow patterns automatically
2. Accuracy: Migrated workflows validate against 1.0.0 schema
3. Clarity: Migration reports provide actionable guidance for manual steps
4. Usability: Tool is straightforward to install and use
5. Documentation: Clear migration guide and examples

Alternatives Considered

1. Manual Migration Guide Only: Insufficient for complex workflows, doesn't scale
2. Runtime-Level Translation: Adds complexity to runtimes, doesn't help with authoring
3. No Migration Support: Abandons existing users, hinders adoption

Community Input Needed

• Are there specific workflow patterns that must be supported?
• What migration challenges have you encountered?
• What should the migration report contain to be most useful?
• Should the tool support batch processing of multiple workflows?

Next Steps

If this proposal is accepted:

1. Create detailed Architecture Decision Record (ADR) with implementation specifics
2. Develop tool in Go (aligns with CNCF ecosystem)
3. Release in phases (MVP → Full Feature Set → Production Ready)
4. Gather community feedback and iterate