From 233accb0f95c3c9e192645cae9823caaf6e6baeb Mon Sep 17 00:00:00 2001 From: Matthias Pichler Date: Sun, 4 Aug 2024 18:09:20 +0000 Subject: [PATCH 1/3] docs: document string substitution feature Signed-off-by: Matthias Pichler --- dsl.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/dsl.md b/dsl.md index f69bdcc1..5c1be773 100644 --- a/dsl.md +++ b/dsl.md @@ -14,6 +14,7 @@ + [Task Flow](#task-flow) + [Data Flow](#data-flow) + [Runtime Expressions](#runtime-expressions) + - [String Substitution](#string-substitution) - [Arguments](#runtime-expression-arguments) + [Fault Tolerance](#fault-tolerance) + [Timeouts](#timeouts) @@ -198,6 +199,18 @@ CloudFlows defines [several arguments](#runtime-expression-arguments) that runti When the evaluation of an expression fails, runtimes **must** raise an error with type `https://https://serverlessworkflow.io/spec/1.0.0/errors/expression` and status `400`. +#### String Substitution + +Simple substitution of top level properties within strings is supported in Serverless Workflow DSL. This feature allows authors to embed variables within strings, making it easier to construct dynamic messages or data structures. + +To substitute a variable within a string, use the `{}` syntax. The identifier inside the curly braces will be replaced with its value during runtime evaluation. If no value is found for the identifier, an empty string will be used. + +String substitution has the following limitations compared to runtime expressions: + +- Only top-level properties can be interpolated within strings, thus identifiers are treated verbatim. This means that `{pet.id}` will be replaced with the value of the `"pet.id"` property, not the value of the `id` property of the `pet` property. +- The referenced variable must be of type `string`, `number`, `boolean`, or `null`. If the variable is of a different type an error with type `https://https://serverlessworkflow.io/spec/1.0.0/errors/expression` and status `400` will be raised. +- [Runtime expression arguments](#runtime-expression-arguments) are not available for string substitution. + #### Runtime expression arguments | Name | Type | Description | From 92562e0702384c5b451160afbf4a55b9674b127d Mon Sep 17 00:00:00 2001 From: Matthias Pichler Date: Mon, 5 Aug 2024 06:40:08 +0000 Subject: [PATCH 2/3] docs: document uri template support Signed-off-by: Matthias Pichler --- dsl-reference.md | 38 ++++++++++++++++++++++++++++---------- dsl.md | 13 ------------- schema/workflow.yaml | 6 +++--- 3 files changed, 31 insertions(+), 26 deletions(-) diff --git a/dsl-reference.md b/dsl-reference.md index 5a67fca3..eb019113 100644 --- a/dsl-reference.md +++ b/dsl-reference.md @@ -50,6 +50,7 @@ + [Duration](#duration) + [HTTP Response](#http-response) + [HTTP Request](#http-request) + + [URI Template](#uri-template) ## Abstract @@ -83,7 +84,7 @@ Documents the workflow definition. | dsl | `string` | `yes` | The version of the DSL used to define the workflow. | | namespace | `string` | `yes` | The workflow's namespace.
| | name | `string` | `yes` | The workflow's name.
| -| version | `string` | `yes` | The workflow's [semantic version] +| version | `string` | `yes` | The workflow's [semantic version](https://semver.org/) | | title | `string` | `no` | The workflow's title. | | summary | `string` | `no` | The workflow's Markdown summary. | | tags | `map[string, string]` | `no` | A key/value mapping of the workflow's tags, if any. | @@ -279,7 +280,7 @@ do: Serverless Workflow defines several default functions that **MUST** be supported by all implementations and runtimes: -- [AsyncAPI](#asyncapi) +- [AsyncAPI](#asyncapi-call) - [gRPC](#grpc-call) - [HTTP](#http-call) - [OpenAPI](#openapi-call) @@ -528,9 +529,9 @@ Allows workflows to iterate over a collection of items, executing a defined set | Name | Type | Required | Description| |:--|:---:|:---:|:---| | for.each | `string` | `no` | The name of the variable used to store the current item being enumerated.
Defaults to `item`. | -| for.in | `string` | `yes` | A [runtime expression](#runtime-expressions) used to get the collection to enumerate. | +| for.in | `string` | `yes` | A [runtime expression](./dsl/#runtime-expressions) used to get the collection to enumerate. | | for.at | `string` | `no` | The name of the variable used to store the index of the current item being enumerated.
Defaults to `index`. | -| while | `string` | `no` | A [runtime expression](#runtime-expressions) that represents the condition, if any, that must be met for the iteration to continue. | +| while | `string` | `no` | A [runtime expression](./dsl/#runtime-expressions) that represents the condition, if any, that must be met for the iteration to continue. | | do | [`task`](#task) | `yes` | The task to perform for each item in the collection. | ##### Examples @@ -601,7 +602,6 @@ do: room: ${ .room.number } ``` - #### Listen Provides a mechanism for workflows to await and react to external events, enabling event-driven behavior within workflow systems. @@ -1073,7 +1073,7 @@ Defines an external resource. | Property | Type | Required | Description | |----------|:----:|:--------:|-------------| | name | `string` | `no` | The name, if any, of the defined resource. | -| uri | `string` | `yes` | The URI at which to get the defined resource. | +| uri | [`uri-template`](#uri-template) | `yes` | The URI at which to get the defined resource. | | authentication | [`authentication`](#authentication) | `no` | The authentication policy, or the name of the authentication policy, to use when fecthing the resource. | ##### Examples @@ -1208,8 +1208,8 @@ Defines the fundamentals of an 'oauth2' authentication | Property | Type | Required | Description | |----------|:----:|:--------:|-------------| -| authority | `string` | `yes` | The URI that references the OAuth2 authority to use. | -| grant | `string` | `yes` | The grant type to use. +| authority | [`uri-template`](#uri-template) | `yes` | The URI that references the OAuth2 authority to use. | +| grant | `string` | `yes` | The grant type to use. | | client.id | `string` | `yes` | The client id to use. | | client.secret | `string` | `no` | The client secret to use, if any. | | scopes | `string[]` | `no` | The scopes, if any, to request the token for. | @@ -1346,7 +1346,7 @@ Defines the [Problem Details RFC](https://datatracker.ietf.org/doc/html/rfc7807) | Property | Type | Required | Description | |----------|:----:|:--------:|-------------| -| type | `string` | `yes` | A URI reference that identifies the [`error`](#error) type.
For cross-compatibility concerns, it is strongly recommended to use [Standard Error Types](#standard-error-types) whenever possible.
Runtimes **MUST** ensure that the property has been set when raising or escalating the [`error`](#error). | +| type | [`uri-template`](#uri-template) | `yes` | A URI reference that identifies the [`error`](#error) type.
For cross-compatibility concerns, it is strongly recommended to use [Standard Error Types](#standard-error-types) whenever possible.
Runtimes **MUST** ensure that the property has been set when raising or escalating the [`error`](#error). | | status | `integer` | `yes` | The status code generated by the origin for this occurrence of the [`error`](#error).
For cross-compatibility concerns, it is strongly recommended to use [HTTP Status Codes](https://datatracker.ietf.org/doc/html/rfc7231#section-6) whenever possible.
Runtimes **MUST** ensure that the property has been set when raising or escalating the [`error`](#error). | | instance | `string` | `yes` | A [JSON Pointer](https://datatracker.ietf.org/doc/html/rfc6901) used to reference the component the [`error`](#error) originates from.
Runtimes **MUST** set the property when raising or escalating the [`error`](#error). Otherwise ignore. | | title | `string` | `no` | A short, human-readable summary of the [`error`](#error). | @@ -1685,4 +1685,22 @@ method: get uri: https://petstore.swagger.io/v2/pet/1 headers: Content-Type: application/json -``` \ No newline at end of file +``` + +### URI Template + +The DSL has limited support for URI template syntax as defined by [RFC 6570](https://datatracker.ietf.org/doc/html/rfc6570). Specifically, only the [Simple String Expansion](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.2) is supported, which allows authors to embed variables in a URI. + +To substitute a variable within a URI, use the `{}` syntax. The identifier inside the curly braces will be replaced with its value during runtime evaluation. If no value is found for the identifier, an empty string will be used. + +This has the following limitations compared to runtime expressions: + +- Only top-level properties can be interpolated within strings, thus identifiers are treated verbatim. This means that `{pet.id}` will be replaced with the value of the `"pet.id"` property, not the value of the `id` property of the `pet` property. +- The referenced variable must be of type `string`, `number`, `boolean`, or `null`. If the variable is of a different type an error with type `https://https://serverlessworkflow.io/spec/1.0.0/errors/expression` and status `400` will be raised. +- [Runtime expression arguments](./dsl.md#runtime-expression-arguments) are not available for string substitution. + +#### Examples + +```yaml +uri: https://petstore.swagger.io/v2/pet/{petId} +``` diff --git a/dsl.md b/dsl.md index 5c1be773..f69bdcc1 100644 --- a/dsl.md +++ b/dsl.md @@ -14,7 +14,6 @@ + [Task Flow](#task-flow) + [Data Flow](#data-flow) + [Runtime Expressions](#runtime-expressions) - - [String Substitution](#string-substitution) - [Arguments](#runtime-expression-arguments) + [Fault Tolerance](#fault-tolerance) + [Timeouts](#timeouts) @@ -199,18 +198,6 @@ CloudFlows defines [several arguments](#runtime-expression-arguments) that runti When the evaluation of an expression fails, runtimes **must** raise an error with type `https://https://serverlessworkflow.io/spec/1.0.0/errors/expression` and status `400`. -#### String Substitution - -Simple substitution of top level properties within strings is supported in Serverless Workflow DSL. This feature allows authors to embed variables within strings, making it easier to construct dynamic messages or data structures. - -To substitute a variable within a string, use the `{}` syntax. The identifier inside the curly braces will be replaced with its value during runtime evaluation. If no value is found for the identifier, an empty string will be used. - -String substitution has the following limitations compared to runtime expressions: - -- Only top-level properties can be interpolated within strings, thus identifiers are treated verbatim. This means that `{pet.id}` will be replaced with the value of the `"pet.id"` property, not the value of the `id` property of the `pet` property. -- The referenced variable must be of type `string`, `number`, `boolean`, or `null`. If the variable is of a different type an error with type `https://https://serverlessworkflow.io/spec/1.0.0/errors/expression` and status `400` will be raised. -- [Runtime expression arguments](#runtime-expression-arguments) are not available for string substitution. - #### Runtime expression arguments | Name | Type | Description | diff --git a/schema/workflow.yaml b/schema/workflow.yaml index c4fd8a69..31fece1c 100644 --- a/schema/workflow.yaml +++ b/schema/workflow.yaml @@ -730,7 +730,7 @@ $defs: properties: authority: type: string - format: uri + format: uri-template description: The URI that references the OAuth2 authority to use. grant: type: string @@ -940,14 +940,14 @@ $defs: externalResource: oneOf: - type: string - format: uri + format: uri-template - title: ExternalResourceURI type: object unevaluatedProperties: false properties: uri: type: string - format: uri + format: uri-template description: The endpoint's URI. authentication: $ref: '#/$defs/referenceableAuthenticationPolicy' From caec8ab55bebf5d12ca598dd774817c9907a67b1 Mon Sep 17 00:00:00 2001 From: Matthias Pichler Date: Mon, 5 Aug 2024 08:09:58 +0000 Subject: [PATCH 3/3] fix: broken links Signed-off-by: Matthias Pichler --- dsl-reference.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/dsl-reference.md b/dsl-reference.md index eb019113..6f97be12 100644 --- a/dsl-reference.md +++ b/dsl-reference.md @@ -529,9 +529,9 @@ Allows workflows to iterate over a collection of items, executing a defined set | Name | Type | Required | Description| |:--|:---:|:---:|:---| | for.each | `string` | `no` | The name of the variable used to store the current item being enumerated.
Defaults to `item`. | -| for.in | `string` | `yes` | A [runtime expression](./dsl/#runtime-expressions) used to get the collection to enumerate. | +| for.in | `string` | `yes` | A [runtime expression](./dsl.md/#runtime-expressions) used to get the collection to enumerate. | | for.at | `string` | `no` | The name of the variable used to store the index of the current item being enumerated.
Defaults to `index`. | -| while | `string` | `no` | A [runtime expression](./dsl/#runtime-expressions) that represents the condition, if any, that must be met for the iteration to continue. | +| while | `string` | `no` | A [runtime expression](./dsl.md/#runtime-expressions) that represents the condition, if any, that must be met for the iteration to continue. | | do | [`task`](#task) | `yes` | The task to perform for each item in the collection. | ##### Examples