Skip to content

Commit 434e0eb

Browse files
Merge pull request serverlessworkflow#955 from matthias-pichler-warrify/string-substitution
Document limited uri-template support
2 parents 7fcc3ca + 808d72b commit 434e0eb

File tree

2 files changed

+31
-13
lines changed

2 files changed

+31
-13
lines changed

dsl-reference.md

Lines changed: 28 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@
5050
+ [Duration](#duration)
5151
+ [HTTP Response](#http-response)
5252
+ [HTTP Request](#http-request)
53+
+ [URI Template](#uri-template)
5354

5455
## Abstract
5556

@@ -83,7 +84,7 @@ Documents the workflow definition.
8384
| dsl | `string` | `yes` | The version of the DSL used to define the workflow. |
8485
| namespace | `string` | `yes` | The workflow's namespace.<br> |
8586
| name | `string` | `yes` | The workflow's name.<br> |
86-
| version | `string` | `yes` | The workflow's [semantic version]
87+
| version | `string` | `yes` | The workflow's [semantic version](https://semver.org/) |
8788
| title | `string` | `no` | The workflow's title. |
8889
| summary | `string` | `no` | The workflow's Markdown summary. |
8990
| tags | `map[string, string]` | `no` | A key/value mapping of the workflow's tags, if any. |
@@ -279,7 +280,7 @@ do:
279280

280281
Serverless Workflow defines several default functions that **MUST** be supported by all implementations and runtimes:
281282

282-
- [AsyncAPI](#asyncapi)
283+
- [AsyncAPI](#asyncapi-call)
283284
- [gRPC](#grpc-call)
284285
- [HTTP](#http-call)
285286
- [OpenAPI](#openapi-call)
@@ -528,9 +529,9 @@ Allows workflows to iterate over a collection of items, executing a defined set
528529
| Name | Type | Required | Description|
529530
|:--|:---:|:---:|:---|
530531
| for.each | `string` | `no` | The name of the variable used to store the current item being enumerated.<br>Defaults to `item`. |
531-
| for.in | `string` | `yes` | A [runtime expression](#runtime-expressions) used to get the collection to enumerate. |
532+
| for.in | `string` | `yes` | A [runtime expression](./dsl.md/#runtime-expressions) used to get the collection to enumerate. |
532533
| for.at | `string` | `no` | The name of the variable used to store the index of the current item being enumerated.<br>Defaults to `index`. |
533-
| while | `string` | `no` | A [runtime expression](#runtime-expressions) that represents the condition, if any, that must be met for the iteration to continue. |
534+
| 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. |
534535
| do | [`task`](#task) | `yes` | The task to perform for each item in the collection. |
535536

536537
##### Examples
@@ -601,7 +602,6 @@ do:
601602
room: ${ .room.number }
602603
```
603604

604-
605605
#### Listen
606606

607607
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.
10731073
| Property | Type | Required | Description |
10741074
|----------|:----:|:--------:|-------------|
10751075
| name | `string` | `no` | The name, if any, of the defined resource. |
1076-
| uri | `string` | `yes` | The URI at which to get the defined resource. |
1076+
| uri | [`uri-template`](#uri-template) | `yes` | The URI at which to get the defined resource. |
10771077
| authentication | [`authentication`](#authentication) | `no` | The authentication policy, or the name of the authentication policy, to use when fecthing the resource. |
10781078

10791079
##### Examples
@@ -1208,8 +1208,8 @@ Defines the fundamentals of an 'oauth2' authentication
12081208

12091209
| Property | Type | Required | Description |
12101210
|----------|:----:|:--------:|-------------|
1211-
| authority | `string` | `yes` | The URI that references the OAuth2 authority to use. |
1212-
| grant | `string` | `yes` | The grant type to use.
1211+
| authority | [`uri-template`](#uri-template) | `yes` | The URI that references the OAuth2 authority to use. |
1212+
| grant | `string` | `yes` | The grant type to use. |
12131213
| client.id | `string` | `yes` | The client id to use. |
12141214
| client.secret | `string` | `no` | The client secret to use, if any. |
12151215
| 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)
13461346

13471347
| Property | Type | Required | Description |
13481348
|----------|:----:|:--------:|-------------|
1349-
| type | `string` | `yes` | A URI reference that identifies the [`error`](#error) type. <br><u>For cross-compatibility concerns, it is strongly recommended to use [Standard Error Types](#standard-error-types) whenever possible.<u><br><u>Runtimes **MUST** ensure that the property has been set when raising or escalating the [`error`](#error).<u> |
1349+
| type | [`uri-template`](#uri-template) | `yes` | A URI reference that identifies the [`error`](#error) type. <br><u>For cross-compatibility concerns, it is strongly recommended to use [Standard Error Types](#standard-error-types) whenever possible.<u><br><u>Runtimes **MUST** ensure that the property has been set when raising or escalating the [`error`](#error).<u> |
13501350
| status | `integer` | `yes` | The status code generated by the origin for this occurrence of the [`error`](#error).<br><u>For cross-compatibility concerns, it is strongly recommended to use [HTTP Status Codes](https://datatracker.ietf.org/doc/html/rfc7231#section-6) whenever possible.<u><br><u>Runtimes **MUST** ensure that the property has been set when raising or escalating the [`error`](#error).<u> |
13511351
| instance | `string` | `yes` | A [JSON Pointer](https://datatracker.ietf.org/doc/html/rfc6901) used to reference the component the [`error`](#error) originates from.<br><u>Runtimes **MUST** set the property when raising or escalating the [`error`](#error). Otherwise ignore.<u> |
13521352
| title | `string` | `no` | A short, human-readable summary of the [`error`](#error). |
@@ -1685,4 +1685,22 @@ method: get
16851685
uri: https://petstore.swagger.io/v2/pet/1
16861686
headers:
16871687
Content-Type: application/json
1688-
```
1688+
```
1689+
1690+
### URI Template
1691+
1692+
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.
1693+
1694+
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.
1695+
1696+
This has the following limitations compared to runtime expressions:
1697+
1698+
- 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.
1699+
- 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.
1700+
- [Runtime expression arguments](./dsl.md#runtime-expression-arguments) are not available for string substitution.
1701+
1702+
#### Examples
1703+
1704+
```yaml
1705+
uri: https://petstore.swagger.io/v2/pet/{petId}
1706+
```

schema/workflow.yaml

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -730,7 +730,7 @@ $defs:
730730
properties:
731731
authority:
732732
type: string
733-
format: uri
733+
format: uri-template
734734
description: The URI that references the OAuth2 authority to use.
735735
grant:
736736
type: string
@@ -940,14 +940,14 @@ $defs:
940940
externalResource:
941941
oneOf:
942942
- type: string
943-
format: uri
943+
format: uri-template
944944
- title: ExternalResourceURI
945945
type: object
946946
unevaluatedProperties: false
947947
properties:
948948
uri:
949949
type: string
950-
format: uri
950+
format: uri-template
951951
description: The endpoint's URI.
952952
authentication:
953953
$ref: '#/$defs/referenceableAuthenticationPolicy'

0 commit comments

Comments
 (0)