docs: document uri template support

Signed-off-by: Matthias Pichler <[email protected]>

Author: matthias-pichler

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.<br> |
 | name | `string` | `yes` | The workflow's name.<br> |
-| 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.<br>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.<br>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. <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> |
+| 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> |
 | 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> |
 | 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> |
 | 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
-```
+```
+
+### 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}
+```

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 |

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'