Proposal: Shared CNCF Workflow Specification Editor & Multi-Maintainer Collaboration Model

[ricardozanini]

Background

During a maintainer sync (@ricardozanini, @JBBianchi, @geomagilles, @mrsimonemms, and Handrey), we discussed the need for a shared editor for the CNCF Workflow Specification that can be used by multiple implementations (Quarkus Flow, SonataFlow, ZigFlow, Synapse, Lemline, etc.).

Today we have:

• An existing (but aging) VS Code extension for Serverless Workflow.
• Several product-specific editors embedded in consoles or IDEs.
• Fragmented UX and duplicated effort around:
  • YAML/JSON authoring
  • Visual diagramming
  • Validation against the spec schema

We want to converge on a single core editor stack driven by the CNCF Workflow Specification, with a collaboration model that allows multiple vendors/maintainers to contribute and embed it.

This issue captures the requirements and proposes a plan.

---

Goals

1. Define the requirements for a new CNCF Workflow editor (text + visual).
2. Establish a shared architecture that editor consumers can embed (e.g., VS Code, web consoles).
3. Define a multi-maintainer governance model (who owns what, how decisions are made).
4. Identify short-term deliverables (1.0) vs. future enhancements (multi-impl features, advanced UX).

Non-goals (for now):

• Implementing a full real-time collaborative editor (multi-user editing).
• Solving all vendor-specific UX needs on day one.
• Supporting every possible runtime-specific extension in the first iteration.

---

Functional Requirements

1. Spec-Driven Authoring

• First-class support for CNCF Workflow Spec (current and future versions, e.g. 1.0.x, 1.1.x).
• Authoring and editing of:
  • Workflows (YAML/JSON)
  • Functions/tasks (HTTP, OpenAPI, Java functions, events, a2a, etc.)
  • Subflows / “do” tasks / nested structures.
• Inline validation against the official JSON Schema:
  • Required fields, enums, types.
  • Helpful error messages with locations in the document.
• Awareness of DSL conventions (e.g., common shortcuts/sugar where applicable).

2. Dual Text + Visual Representation

• Text editor:
  • Syntax highlighting for CNCF Workflow.
  • Auto-completion/intellisense based on schema (fields, enums).
  • Snippets/boilerplates for common patterns (sequences, branches, event listeners, HTTP tasks).
• Visual editor:
  • Node/edge diagram representation of the workflow.
  • Drag-and-drop to add tasks, events, and transitions.
  • Support for nested/compound tasks (e.g. “do” tasks with children).
• Round-trip between text and diagram:
  • Changes in text are reflected in the diagram.
  • Changes in the diagram are persisted back to YAML/JSON.
  • Single source of truth remains the spec-compliant document.

3. Embeddable Core Component

We want a core editor engine that can be reused across environments:

• Distributed as an NPM package / web component / embeddable module.
• Host applications (VS Code extension, web consoles, management UIs) should be able to:
  • Provide the workflow document (string or model) and receive updates.
  • Configure read-only vs editable modes.
  • Wire the editor’s callbacks into their own persistence & execution APIs.
• The VS Code extension should:
  • Use this shared core for both text & visual modes.
  • Stay thin: mostly wiring, not re-implementing editor logic.

4. Implementation-Specific Extensions (Future-Ready)

Even though 1.0.0 doesn’t need all of this, the architecture should not block:

• Extension points for implementation-specific schema additions:
  • Example: “this runtime doesn’t support feature X; hide/disable it”.
  • Example: “this runtime adds additional metadata; surface it”.
• Ability to load custom schema fragments or configuration that:
  • Enable/disable features in the UI.
  • Control which components are visible/available.
• Support for multiple “profiles” (e.g., Quarkus Flow profile, SonataFlow profile) that adjust the editor behavior.

---

Non-Functional Requirements

• Open governance:
  • Hosted under the CNCF Workflow / Serverless Workflow GitHub org.
  • Maintainer list includes representatives from multiple vendors/engines.
• Licensing: Apache-2.0 (aligned with spec and existing repos).
• Tech stack (initial proposal):
  • Web-based (TypeScript/React or equivalent), schema-driven.
  • Consumable in:
    • VS Code (extension)
    • Browser-based embedding (e.g., consoles, docs, workshops).
• Performance & UX:
  • Responsive for medium-large workflows (hundreds of nodes).
  • Clear separation between “simple” authoring UX and advanced features.
• Testability & CI:
  • Schema-based test coverage (example workflows should render and validate).
  • Visual regression tests where practical.

---

Governance & Collaboration Model

We want a multi-maintainer editor project that does not belong to a single vendor.

Proposed model:

• Repository ownership:
  • New repo under CNCF Workflow org, e.g. workflow-spec-editor (name TBD).
• Maintainers:
  • Initial maintainers: representatives from at least:
    • CNCF Workflow Spec maintainers
    • Quarkus Flow / SonataFlow
    • Other interested engine maintainers (e.g., Zigflow / Synapse / Lemline etc.).
• Decision process:
  • Use the spec’s existing governance as a reference (PR review rules, approvals).
  • Editor decisions should:
    • Respect the spec as the single source of truth.
    • Avoid baking in engine-specific opinions by default.
• Integration responsibilities:
  • Core editor project provides:
    • NPM package(s)
    • Reference VS Code extension
    • Docs, examples.
  • Each implementation (Quarkus Flow, Synapse, etc.) owns:
    • Their integration/embedding.
    • Optional extension/profile configuration.
• Release strategy:
  • Align with spec releases when possible (e.g., new spec fields -> new editor release).
  • Support at least the latest minor and one previous minor version of the spec.

---

Initial Scope (v1.0)

Concretely, for a 1.0 we propose:

1. New repo & governance
   • Create CNCF Workflow Editor repo.
   • Seed MAINTAINERS file and CONTRIBUTING guidelines.
2. Core web editor
   • Text + validation + minimal diagram.
   • Shared data model from the official JSON Schema.
3. VS Code extension using the core
   • Package on VS Code Marketplace as the official CNCF Workflow editor.
   • Mark the existing legacy extension as deprecated once feature parity is reasonable.
4. Basic embedding story
   • A simple demo app showing how to embed the editor as a component.
   • Documentation for integrators.

---

Future Enhancements (Out of Scope for v1.0)

• Multi-user collaborative editing (OT/CRDT, presence, comments).
• Rich execution overlays:
  • Visualizing execution paths, success/failure on nodes.
  • Integrations with observability/tracing.
• Deep implementation profiles with runtime capability matrices.
• Built-in templates for complex agentic workflows / AI patterns.

---

Open Questions

1. Tech stack & implementation detail
   • Do we commit to a specific UI framework now (e.g., React) or keep the core more framework-agnostic?
2. Migration from existing editors
   • How do we coordinate deprecation/migration of:
     • Current VS Code extension(s).
     • Vendor-specific editors that may already exist?
3. Versioning strategy
   • How tightly should editor releases track spec versions?
4. Funding & sponsorship
   • Do we need ongoing funding for design/UX work beyond volunteer efforts?

---

Proposed Next Steps

1. Confirm high-level requirements and goals in this issue.
2. Agree on repo name and location under the CNCF Workflow/Serverless Workflow org.
3. Nominate initial maintainers representing at least 3 implementations.
4. Draft a short architecture doc for:
   • Core editor package.
   • VS Code extension.
   • Embedding API.
5. Schedule a follow-up working session to:
   • Review the architecture doc.
   • Create initial GitHub milestones for v1.0.

• Please vote by adding a 👍 reaction to the feature to help us prioritize.
• If you are interested to work on this feature, please leave a comment.