From 89874335ebd015f9e72b27573efb3d1df6b70057 Mon Sep 17 00:00:00 2001 From: Dmitriy Date: Tue, 30 Jun 2026 15:57:04 +0500 Subject: [PATCH] Fix further dsl-reference.md / schema/workflow.yaml mismatches Follow-up to the mismatches reported in #1156: Doc alignments (dsl-reference.md): - Add the required `namespace` property to the Run -> Workflow Process table. - Remove the spurious `extension` value from the extension `extend` enum (there is no "extension" task type). - Mark AsyncAPI `channel`/`operation` as optional; they are mutually alternative depending on the AsyncAPI version, not both required. - Document catch `errors.with` as the static error filter, matching the schema and examples. - Lowercase the Duration property names (days, hours, ...) to match the schema keys. - Document the `pullPolicy` enum values (ifNotPresent, always, never). - Change `issuers` from `uri-template[]` to `string[]` to match the schema and RFC 7519 (StringOrURI). Script language token (js): - Standardize the script language token on `js` (as used by the Java SDK), replacing `javascript` in dsl-reference.md, dsl.md and the example. Schema (schema/workflow.yaml): - Rename the errorFilter `details` property to `detail`, matching the `error` definition and RFC 7807. - Require `authority` and `grant` for inline OAuth2/OIDC authentication (oauth2AuthenticationProperties); `grant_type` is REQUIRED per RFC 6749 and neither field has a default. Co-Authored-By: Claude Opus 4.8 (1M context) Signed-off-by: Dmitriy --- dsl-reference.md | 34 +++++++++++-------- dsl.md | 2 +- .../run-script-with-stdin-and-arguments.yaml | 2 +- schema/workflow.yaml | 5 +-- 4 files changed, 24 insertions(+), 19 deletions(-) diff --git a/dsl-reference.md b/dsl-reference.md index 212c9802..23156db3 100644 --- a/dsl-reference.md +++ b/dsl-reference.md @@ -332,14 +332,17 @@ The [AsyncAPI Call](#asyncapi-call) enables workflows to interact with external | Name | Type | Required | Description | |:-----|:----:|:--------:|:------------| | document | [`externalResource`](#external-resource) | `yes` | The AsyncAPI document that defines the [operation](https://www.asyncapi.com/docs/reference/specification/v3.0.0#operationObject) to call. | -| channel | `string` | `yes` | The name of the channel on which to perform the operation. The operation to perform is defined by declaring either `message`, in which case the [channel](https://v2.asyncapi.com/docs/reference/specification/v2.6.0#channelItemObject)'s `publish` operation will be executed, or `subscription`, in which case the [channel](https://v2.asyncapi.com/docs/reference/specification/v2.6.0#channelItemObject)'s `subscribe` operation will be executed.
*Used only in case the referenced document uses AsyncAPI `v2.6.0`.* | -| operation | `string` | `yes` | A reference to the AsyncAPI [operation](https://www.asyncapi.com/docs/reference/specification/v3.0.0#operationObject) to call.
*Used only in case the referenced document uses AsyncAPI `v3.0.0`.* | +| channel | `string` | `no` | The name of the channel on which to perform the operation. The operation to perform is defined by declaring either `message`, in which case the [channel](https://v2.asyncapi.com/docs/reference/specification/v2.6.0#channelItemObject)'s `publish` operation will be executed, or `subscription`, in which case the [channel](https://v2.asyncapi.com/docs/reference/specification/v2.6.0#channelItemObject)'s `subscribe` operation will be executed.
*Used only in case the referenced document uses AsyncAPI `v2.6.0`.* | +| operation | `string` | `no` | A reference to the AsyncAPI [operation](https://www.asyncapi.com/docs/reference/specification/v3.0.0#operationObject) to call.
*Used only in case the referenced document uses AsyncAPI `v3.0.0`.* | | server | [`asyncApiServer`](#asyncapi-server) | `no` | An object used to configure to the [server](https://www.asyncapi.com/docs/reference/specification/v3.0.0#serverObject) to call the specified AsyncAPI [operation](https://www.asyncapi.com/docs/reference/specification/v3.0.0#operationObject) on.
If not set, default to the first [server](https://www.asyncapi.com/docs/reference/specification/v3.0.0#serverObject) matching the operation's channel. | | protocol | `string` | `no` | The [protocol](https://www.asyncapi.com/docs/reference/specification/v3.0.0#definitionsProtocol) to use to select the target [server](https://www.asyncapi.com/docs/reference/specification/v3.0.0#serverObject).
Ignored if `server` has been set.
*Supported values are: `amqp`, `amqp1`, `anypointmq`, `googlepubsub`, `http`, `ibmmq`, `jms`, `kafka`, `mercure`, `mqtt`, `mqtt5`, `nats`, `pulsar`, `redis`, `sns`, `solace`, `sqs`, `stomp` and `ws`* | | message | [`asyncApiMessage`](#asyncapi-outbound-message) | `no` | An object used to configure the message to publish using the target operation.
*Required if `subscription` has not been set.* | | subscription | [`asyncApiSubscription`](#asyncapi-subscription) | `no` | An object used to configure the subscription to messages consumed using the target operation.
*Required if `message` has not been set.* | | authentication | `string`
[`authentication`](#authentication) | `no` | The authentication policy, or the name of the authentication policy, to use when calling the AsyncAPI operation. | +> [!NOTE] +> Exactly one of `channel` (AsyncAPI `v2.6.0`) or `operation` (AsyncAPI `v3.0.0`) **must** be set, paired with exactly one of `message` or `subscription`. + ###### Examples ```yaml @@ -895,7 +898,7 @@ do: - runScript: run: script: - language: javascript + language: js code: > Some cool multiline script @@ -930,7 +933,7 @@ Enables the execution of external processes encapsulated within a containerized | stdin | `string` | `no` | A runtime expression, if any, passed as standard input to the command or default container CMD| | arguments | `string[]` | `no` | A list of the arguments, if any, passed as argv to the command or default container CMD | | lifetime | [`containerLifetime`](#container-lifetime) | `no` | An object used to configure the container's lifetime. | -| pullPolicy | `string` | `no` | Policy that controls how the container's image should be pulled from the registry. Defaults to `ifNotPresent` | +| pullPolicy | `string` | `no` | Policy that controls how the container's image should be pulled from the registry.
*Supported values are `ifNotPresent`, `always` and `never`.*
*Defaults to `ifNotPresent`.* | ###### Examples @@ -1003,7 +1006,7 @@ do: - runScript: run: script: - language: javascript + language: js arguments: - hello - world @@ -1060,6 +1063,7 @@ Enables the invocation and execution of nested workflows within a parent workflo | Name | Type | Required | Description | |:--|:---:|:---:|:---| +| namespace | `string` | `yes` | The namespace the workflow to run belongs to. | | name | `string` | `yes` | The name of the workflow to run | | version | `string` | `yes` | The version of the workflow to run. Defaults to `latest` | | input | `any` | `no` | The data, if any, to pass as input to the workflow to execute. The value should be validated against the target workflow's input schema, if specified | @@ -1245,7 +1249,7 @@ Defines the configuration of a catch clause, which a concept used to catch error | Name | Type | Required | Description | |:--|:---:|:---:|:---| -| errors | [`errorFilter`](#error) | `no` | The definition of the errors to catch. | +| errors.with | [`errorFilter`](#error) | `no` | A static filter, used to catch only the errors whose properties match the specified values. | | as | `string` | `no` | The name of the runtime expression variable to save the error as. Defaults to 'error'. | | when | `string`| `no` | A runtime expression used to determine whether or not to catch the filtered error. | | exceptWhen | `string` | `no` | A runtime expression used to determine whether or not to catch the filtered error. | @@ -1857,7 +1861,7 @@ Defines the fundamentals of an 'oauth2' authentication. | client.assertion | `string` | `no` | A JWT containing a signed assertion with your application credentials.
Required when `client.authentication` has been set to `private_key_jwt`. | | client.authentication | `string` | `no` | The client authentication method to use.
Supported values are `client_secret_basic`, `client_secret_post`, `client_secret_jwt`, `private_key_jwt` or `none`.
Defaults to `client_secret_post`. | | request.encoding | `string` | `no` | The encoding of the token request.
Supported values are `application/x-www-form-urlencoded` and `application/json`.
Defaults to application/x-www-form-urlencoded. | -| issuers | `uri-template[]` | `no` | A list that contains that contains valid issuers that will be used to check against the issuer of generated tokens. | +| issuers | `string[]` | `no` | A list that contains valid issuers that will be used to check against the issuer of generated tokens. | | scopes | `string[]` | `no` | The scopes, if any, to request the token for. | | audiences | `string[]` | `no` | The audiences, if any, to request the token for. | | username | `string` | `no` | The username to use. Used only if the grant type is `Password`. | @@ -1919,7 +1923,7 @@ Defines the fundamentals of an 'oidc' authentication. | client.assertion | `string` | `no` | A JWT containing a signed assertion with your application credentials.
Required when `client.authentication` has been set to `private_key_jwt`. | | client.authentication | `string` | `no` | The client authentication method to use.
Supported values are `client_secret_basic`, `client_secret_post`, `client_secret_jwt`, `private_key_jwt` or `none`.
Defaults to `client_secret_post`. | | request.encoding | `string` | `no` | The encoding of the token request.
Supported values are `application/x-www-form-urlencoded` and `application/json`.
Defaults to application/x-www-form-urlencoded. | -| issuers | `uri-template[]` | `no` | A list that contains that contains valid issuers that will be used to check against the issuer of generated tokens. | +| issuers | `string[]` | `no` | A list that contains valid issuers that will be used to check against the issuer of generated tokens. | | scopes | `string[]` | `no` | The scopes, if any, to request the token for. | | audiences | `string[]` | `no` | The audiences, if any, to request the token for. | | username | `string` | `no` | The username to use. Used only if the grant type is `Password`. | @@ -2001,7 +2005,7 @@ Extensions enable the execution of tasks prior to those they extend, offering th | Property | Type | Required | Description | |----------|:----:|:--------:|-------------| -| extend | `string` | `yes` | The type of task to extend
Supported values are: `call`, `composite`, `emit`, `extension`, `for`, `listen`, `raise`, `run`, `set`, `switch`, `try`, `wait` and `all` | +| extend | `string` | `yes` | The type of task to extend
Supported values are: `call`, `composite`, `emit`, `for`, `listen`, `raise`, `run`, `set`, `switch`, `try`, `wait` and `all` | | when | `string` | `no` | A runtime expression used to determine whether or not the extension should apply in the specified context | | before | [`task[]`](#task) | `no` | The list of tasks to execute, if any, before the extended task | | after | [`task[]`](#task) | `no` | The list of tasks to execute, if any, after the extended task | @@ -2384,11 +2388,11 @@ Defines a duration. Durations can be defined through properties, with an ISO 860 | Property | Type | Required | Description | |----------|:----:|:--------:|-------------| -| Days | `integer` | `no` | Number of days, if any. | -| Hours | `integer` | `no` | Number of hours, if any. | -| Minutes | `integer` | `no`| Number of minutes, if any. | -| Seconds | `integer` | `no`| Number of seconds, if any. | -| Milliseconds | `integer` | `no`| Number of milliseconds, if any. | +| days | `integer` | `no` | Number of days, if any. | +| hours | `integer` | `no` | Number of hours, if any. | +| minutes | `integer` | `no`| Number of minutes, if any. | +| seconds | `integer` | `no`| Number of seconds, if any. | +| milliseconds | `integer` | `no`| Number of milliseconds, if any. | #### Examples @@ -2523,7 +2527,7 @@ do: - runScript: run: script: - language: javascript + language: js code: > Some cool multiline script return: code diff --git a/dsl.md b/dsl.md index 2f5e2826..71468760 100644 --- a/dsl.md +++ b/dsl.md @@ -640,7 +640,7 @@ output: description: A boolean indicating whether or not the email address is valid. run: script: - language: javascript + language: js code: | function validateEmail(email) { const re = /^[a-zA-Z0-9._-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,6}$/; diff --git a/examples/run-script-with-stdin-and-arguments.yaml b/examples/run-script-with-stdin-and-arguments.yaml index 07d4fb1b..bd5752c8 100644 --- a/examples/run-script-with-stdin-and-arguments.yaml +++ b/examples/run-script-with-stdin-and-arguments.yaml @@ -7,7 +7,7 @@ do: - runScript: run: script: - language: javascript + language: js stdin: "Hello Workflow" environment: foo: bar diff --git a/schema/workflow.yaml b/schema/workflow.yaml index 34183f3a..a443ed50 100644 --- a/schema/workflow.yaml +++ b/schema/workflow.yaml @@ -1238,6 +1238,7 @@ $defs: type: object title: OAuth2AuthenticationData description: Inline configuration of the OAuth2 authentication policy. + required: [ authority, grant ] properties: authority: $ref: '#/$defs/uriTemplate' @@ -1429,10 +1430,10 @@ $defs: instance: type: string description: if present, means this value should be used for filtering - title: + title: type: string description: if present, means this value should be used for filtering - details: + detail: type: string description: if present, means this value should be used for filtering uriTemplate: