Mismatches between dsl-reference.md and schema/workflow.yaml

[dimastbk]

Disclaimer: This issue was generated by Claude Code.

Summary

While cross-checking dsl-reference.md against the authoritative JSON Schema in schema/workflow.yaml, I found a number of divergences between the prose reference and the schema. They range from outright bugs in the schema to documented features that don't exist in the schema, plus several minor wording/typing inconsistencies.

References below are given as dsl-reference.md:line vs schema/workflow.yaml:line (line numbers as of main).

High — documented but missing/broken in the schema

1. evaluate / Evaluate workflow property is not in the schema

• Doc: workflow property evaluate (dsl-reference.md:110) plus a full Evaluate table with language + mode (dsl-reference.md:153-160).
• Schema: root properties are only document, input, use, do, timeout, output, schedule (workflow.yaml:6-154). There is no evaluate.

2. Certificate authentication is documented but absent from the schema

• Doc: lists certificate as an authentication scheme (dsl-reference.md:1711) and has a "Certificate Authentication" section (dsl-reference.md:1808, body empty).
• Schema: authenticationPolicy.oneOf only contains basic, bearer, digest, oauth2, oidc (workflow.yaml:1094-1219). No certificate.

3. MCP Client — version is required but never defined (schema bug)

• Doc: MCP Client = name (yes) + version (yes) (dsl-reference.md:2857-2860).
• Schema: McpClient defines name and description (the description property is even mis-titled McpClientVersion), but declares required: [ name, version ] — version is not a defined property (workflow.yaml:563-576). So the schema requires a nonexistent property and exposes an undocumented description property.

Medium

4. Run → Workflow Process: required namespace missing from the doc table

• Doc: property table lists only name, version, input (dsl-reference.md:1062-1066) — no namespace, even though the examples use it.
• Schema: SubflowConfiguration requires [ namespace, name, version ] (workflow.yaml:919-937).

5. Extension extend enum has an extra value in the doc

• Doc: call, composite, emit, extension, for, listen, raise, run, set, switch, try, wait, all (dsl-reference.md:2009).
• Schema: call, composite, emit, for, listen, raise, run, set, switch, try, wait, all — no extension (workflow.yaml:1587).

6. MCP protocolVersion required flag

• Doc: protocolVersion marked required yes (dsl-reference.md:539).
• Schema: with.required is [ method, transport ]; protocolVersion is optional with default 2025-06-18 (workflow.yaml:492-577). Given the default, it should be no.

Minor / representational

7. OAuth2 & OIDC authority/grant required flag — doc marks both yes (dsl-reference.md:1855,1859,1920,1921), but oauth2AuthenticationProperties declares no required (workflow.yaml:1220-1301).
8. OAuth2/OIDC issuers type — doc says uri-template[] (dsl-reference.md:1865,1927); schema is string[] (workflow.yaml:1268-1273).
9. AsyncAPI Call channel vs operation — doc marks both required yes (dsl-reference.md:336-337); schema makes them mutually-alternative via with.oneOf (workflow.yaml:276-280), so neither is unconditionally required.
10. Catch errors shape — doc types it as errorFilter directly (dsl-reference.md:1249); schema models it as an object { with: errorFilter } (workflow.yaml:1009-1015), matching the example at dsl-reference.md:1226.
11. A2A agentCard/server mutual requirement — doc states each is required when the other is unset (dsl-reference.md:498-499); schema enforces no such constraint (only required: [ method ], workflow.yaml:474).
12. Script language constraint — doc restricts to js/python (ES2024 / 3.13) (dsl-reference.md:978,990-993); schema has language: type: string with no enum (workflow.yaml:842-845).
13. Duration property casing — doc table uses Days, Hours, Minutes, Seconds, Milliseconds (dsl-reference.md:2392-2396); schema keys are lowercase days, hours, … (workflow.yaml:1323-1342). Examples use lowercase, so the table headers are misleading.
14. Container pullPolicy — doc omits the allowed values (dsl-reference.md:934); schema enumerates [ ifNotPresent, always, never ] (workflow.yaml:826-830).

Also worth flagging (schema-internal)

The schema's errorFilter uses details (workflow.yaml:1418) while error and the doc use detail (workflow.yaml:1391, dsl-reference.md:2093).

Suggested priority

Items 1 (evaluate), 2 (certificate auth), 3 (MCP client version), and 5 (extension enum) are the substantive divergences. 3 is an outright bug in the schema regardless of the doc.

Note that several fixes are direction-dependent (e.g. should evaluate and certificate be added to the schema or removed from the doc?). Maintainer guidance on which artifact is authoritative for each would help before opening a PR.