From 739d2477386396f365f6d0f1bb4bbe3ef9141b4b Mon Sep 17 00:00:00 2001
From: Dmitriy <dimastbk@proton.me>
Date: Wed, 24 Jun 2026 18:42:30 +0500
Subject: [PATCH] Fix three dsl-reference.md / schema/workflow.yaml mismatches

Resolves the substantive divergences reported in #1156:

- Add the `evaluate` workflow property (`language`, `mode`) to
  schema/workflow.yaml. It is documented in dsl-reference.md and
  referenced by dsl.md (`evaluate.language`) but was missing from the
  schema.
- Remove certificate authentication from dsl-reference.md (TOC entry,
  authentication properties-table row, and the empty section). It is
  not defined in the schema, dsl.md, examples, or the CTK.
- Rename the MCP client schema property `description` -> `version`.
  The schema declared `required: [ name, version ]` but defined no
  `version` property (it was mis-keyed as `description`).

Also align the Evaluate table in dsl-reference.md: `language` and `mode`
are now `no` (both have defaults, so they are optional), matching the
schema.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Dmitriy <dimastbk@proton.me>
---
 dsl-reference.md     |  9 ++-------
 schema/workflow.yaml | 19 ++++++++++++++++++-
 2 files changed, 20 insertions(+), 8 deletions(-)

diff --git a/dsl-reference.md b/dsl-reference.md
index 2a63abe7..bc6ad69b 100644
--- a/dsl-reference.md
+++ b/dsl-reference.md
@@ -57,7 +57,6 @@
   + [Authentication](#authentication)
     - [Basic](#basic-authentication)
     - [Bearer](#bearer-authentication)
-    - [Certificate](#certificate-authentication)
     - [Digest](#digest-authentication)
     - [OAUTH2](#oauth2-authentication)
     - [OpenIdConnect](#openidconnect-authentication)
@@ -156,8 +155,8 @@ Configures a workflow's runtime expression evaluation.
 
 | Name | Type | Required | Description|
 |:--|:---:|:---:|:---|
-| language | `string` | `yes` | The language used for writting runtime expressions.<br>*Defaults to `jq`.* |
-| mode | `string` | `yes` | The runtime expression evaluation mode.<br>*Supported values are:*<br>- `strict`: requires all expressions to be enclosed within `${ }` for proper identification and evaluation.<br>- `loose`: evaluates any value provided. If the evaluation fails, it results in a string with the expression as its content.<br>*Defaults to `strict`.*
+| language | `string` | `no` | The language used for writting runtime expressions.<br>*Defaults to `jq`.* |
+| mode | `string` | `no` | The runtime expression evaluation mode.<br>*Supported values are:*<br>- `strict`: requires all expressions to be enclosed within `${ }` for proper identification and evaluation.<br>- `loose`: evaluates any value provided. If the evaluation fails, it results in a string with the expression as its content.<br>*Defaults to `strict`.*
 
 #### Examples
 
@@ -1708,7 +1707,6 @@ Defines the mechanism used to authenticate users and workflows attempting to acc
 | use | `string` | `no` | The name of the top-level authentication definition to use. Cannot be used by authentication definitions defined at top level. |
 | basic | [`basicAuthentication`](#basic-authentication) | `no` | The `basic` authentication scheme to use, if any.<br>Required if no other property has been set, otherwise ignored. |
 | bearer | [`bearerAuthentication`](#bearer-authentication) | `no` | The `bearer` authentication scheme to use, if any.<br>Required if no other property has been set, otherwise ignored. |
-| certificate | [`certificateAuthentication`](#certificate-authentication) | `no` | The `certificate` authentication scheme to use, if any.<br>Required if no other property has been set, otherwise ignored. |
 | digest | [`digestAuthentication`](#digest-authentication) | `no` | The `digest` authentication scheme to use, if any.<br>Required if no other property has been set, otherwise ignored. |
 | oauth2 | [`oauth2`](#oauth2-authentication) | `no` | The `oauth2` authentication scheme to use, if any.<br>Required if no other property has been set, otherwise ignored. |
 | oidc | [`oidc`](#openidconnect-authentication) | `no` | The `oidc` authentication scheme to use, if any.<br>Required if no other property has been set, otherwise ignored. |
@@ -1805,9 +1803,6 @@ do:
               token: ${ .user.token }
 ```
 
-#### Certificate Authentication
-
-
 #### Digest Authentication
 
 Defines the fundamentals of a 'digest' authentication.
diff --git a/schema/workflow.yaml b/schema/workflow.yaml
index 0bd5cc42..8134ad41 100644
--- a/schema/workflow.yaml
+++ b/schema/workflow.yaml
@@ -152,6 +152,23 @@ properties:
         $ref: '#/$defs/eventConsumptionStrategy'
         title: ScheduleOn
         description: Specifies the events that trigger the workflow execution.
+  evaluate:
+    type: object
+    title: Evaluate
+    description: Configures the workflow's runtime expression evaluation.
+    unevaluatedProperties: false
+    properties:
+      language:
+        type: string
+        default: jq
+        title: EvaluateLanguage
+        description: The language used for writing runtime expressions. Defaults to 'jq'.
+      mode:
+        type: string
+        enum: [ strict, loose ]
+        default: strict
+        title: EvaluateMode
+        description: The runtime expression evaluation mode. Defaults to 'strict'.
 $defs:
   taskList:
     title: TaskList
@@ -569,7 +586,7 @@ $defs:
                       type: string
                       title: McpClientName
                       description: The name of the client used to connect to the MCP server.
-                    description:
+                    version:
                       type: string
                       title: McpClientVersion
                       description: The version of the client used to connect to the MCP server.