Merge pull request #963 from neuroglia-io/fix-917-semantic-inconsistencies-listen-vs-emit

ricardozanini · web-flow · commit 4e03cdb20aa4 · 2024-08-07T09:55:14.000-04:00
Fixed inconsistencies between `listen` and `emit`
diff --git a/ctk/features/set.feature b/ctk/features/set.feature
@@ -3,7 +3,7 @@ Feature: Set Task
   I want to ensure that set tasks can be executed within the workflow
   So that my implementation conforms to the expected behavior
 
-  # Tests emit tasks
+  # Tests set tasks
   Scenario: Set Task
     Given a workflow with definition:
     """yaml
diff --git a/dsl-reference.md b/dsl-reference.md
@@ -25,8 +25,8 @@
         + [Shell](#shell-process)
         + [Script](#script-process)
         + [Workflow](#workflow-process)
-    - [Switch](#switch)
     - [Set](#set)
+    - [Switch](#switch)
     - [Try](#try)
     - [Wait](#wait)
   + [Flow Directive](#flow-directive)
@@ -42,6 +42,7 @@
     - [Standard Error Types](#standard-error-types)
   + [Event Consumption Strategy](#event-consumption-strategy)
   + [Event Filter](#event-filter)
+  + [Event Properties](#event-properties)
   + [Retry](#retry)
   + [Input](#input)
   + [Output](#output)
@@ -230,9 +231,9 @@ The Serverless Workflow DSL defines a list of [tasks](#task) that **must be** su
 - [Call](#call), used to call services and/or functions.
 - [Do](#do), used to define one or more subtasks to perform in sequence.
 - [Fork](#fork), used to define one or more subtasks to perform concurrently.
-- [Emit](#emit), used to emit [events](#event).
+- [Emit](#emit), used to emit [events](#event-properties).
 - [For](#for), used to iterate over a collection of items, and conditionally perform a task for each of them.
-- [Listen](#listen), used to listen for an [event](#event) or more.
+- [Listen](#listen), used to listen for an [event](#event-properties) or more.
 - [Raise](#raise), used to raise an [error](#error) and potentially fault the [workflow](#workflow).
 - [Run](#run), used to run a [container](#container-process), a [script](#script-process) , a [shell](#shell-process) command or even another [workflow](#workflow-process). 
 - [Switch](#switch), used to dynamically select and execute one of multiple alternative paths based on specified conditions
@@ -369,7 +370,7 @@ The [HTTP Call](#http-call) enables workflows to interact with external services
 | Name | Type | Required | Description|
 |:--|:---:|:---:|:---|
 | method | `string` | `yes` | The HTTP request method. |
-| endpoint | [`endpoint`](#endpoint) | `yes` | An URI or an object that describes the HTTP endpoint to call. |
+| endpoint | `string`\|[`endpoint`](#endpoint) | `yes` | An URI or an object that describes the HTTP endpoint to call. |
 | headers | `map` | `no` | A name/value mapping of the HTTP headers to use, if any. |
 | body | `any` | `no` | The HTTP request body, if any. |
 | query | `map[string, any]` | `no` | A name/value mapping of the query parameters to use, if any. |
@@ -496,7 +497,7 @@ Allows workflows to publish events to event brokers or messaging systems, facili
 
 | Name | Type | Required | Description |
 |:--|:---:|:---:|:---|
-| emit.event | [`event`](#event) | `yes` | Defines the event to emit. |
+| emit.event | [`eventProperties`](#event-properties) | `yes` | Defines the event to emit. |
 
 ##### Examples
 
@@ -510,15 +511,16 @@ do:
   - emitEvent:
       emit:
         event:
-          source: https://petstore.com
-          type: com.petstore.order.placed.v1
-          data:
-            client:
-              firstName: Cruella
-              lastName: de Vil
-            items:
-              - breed: dalmatian
-                quantity: 101
+          with:
+            source: https://petstore.com
+            type: com.petstore.order.placed.v1
+            data:
+              client:
+                firstName: Cruella
+                lastName: de Vil
+              items:
+                - breed: dalmatian
+                  quantity: 101
 ```
 
 #### For
@@ -530,9 +532,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](./dsl.md/#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.<br>Defaults to `index`. |
-| 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. |
+| 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
@@ -965,7 +967,7 @@ do:
 
 ##### Switch Case
 
-Defines a switch case, encompassing of a condition for matching and an associated action to execute upon a match.
+Defines a switch case, encompassing a condition for matching and an associated action to execute upon a match.
 
 | Name | Type | Required | Description |
 |:--|:---:|:---:|:---|
@@ -1390,6 +1392,28 @@ Represents the configuration of an event consumption strategy.
 | any | [`eventFilter[]`](#event-filter) | `no` | Configures the workflow to wait for any of the defined events before resuming execution.<br>*Required if `all` and `one` have not been set.* |
 | one | [`eventFilter`](#event-filter) | `no` | Configures the workflow to wait for the defined event before resuming execution.<br>*Required if `all` and `any` have not been set.* |
 
+### Event Properties
+
+An event object typically includes details such as the event type, source, timestamp, and unique identifier along with any relevant data payload. The [Cloud Events specification](https://cloudevents.io/), favored by Serverless Workflow, standardizes this structure to ensure interoperability across different systems and services.
+
+#### Properties
+
+| Property | Type | Required | Description |
+|----------|:----:|:--------:|-------------|
+| id | `string` | `no` | Identifies the event. `source` + `id` is unique for each distinct event.<br>*Required when emitting an event using `emit.event.with`.* |
+| source | `string` | `no` | An URI formatted string, or [runtime expression](dsl.md#runtime-expressions), that identifies the context in which an event happened. `source` + `id` is unique for each distinct event.<br>*Required when emitting an event using `emit.event.with`.* |
+| type | `string` | `no` | Describes the type of event related to the originating occurrence.<br>*Required when emitting an event using `emit.event.with`.* |
+| time | `string` | `no` | A string, or [runtime expression](dsl.md#runtime-expressions), representing the timestamp of when the occurrence happened. |
+| subject | `string` | `no` | Describes the subject of the event in the context of the event producer. |
+| datacontenttype | `string` | `no` | Content type of `data` value. If omitted, it implies the `data` is a JSON value conforming to the "application/json" media type. |
+| dataschema | `string` | `no` | An URI formatted string, or [runtime expression](dsl.md#runtime-expressions), that identifies the schema that `data` adheres to. |
+| data | `object` | `no` | The event payload. |
+
+*Additional properties can be supplied, see the Cloud Events specification [documentation](https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#extension-context-attributes) for more info.*
+
+*When used in an [`eventFilter`](#event-filter), at least one property must be supplied.*
+
+
 ### Event Filter
 
 An event filter is a mechanism used to selectively process or handle events based on predefined criteria, such as event type, source, or specific attributes.
@@ -1398,7 +1422,7 @@ An event filter is a mechanism used to selectively process or handle events base
 
 | Property | Type | Required | Description |
 |----------|:----:|:--------:|-------------|
-| with | `object` | `yes` | A name/value mapping of the attributes filtered events must define. Supports both regular expressions and runtime expressions.  |
+| with | [`eventProperties`](#event-properties) | `yes` | A name/value mapping of the attributes filtered events must define. Supports both regular expressions and runtime expressions.  |
 | correlate | [`map[string, correlation]`](#correlation) | `no` | A name/definition mapping of the correlations to attempt when filtering events. |
 
 ### Correlation
@@ -1474,7 +1498,7 @@ When set, runtimes must validate input data against the defined schema, unless d
 | Property | Type | Required | Description |
 |----------|:----:|:--------:|-------------|
 | schema | [`schema`](#schema) | `no` | The [`schema`](#schema) used to describe and validate input data.<br>*Even though the schema is not required, it is strongly encouraged to document it, whenever feasible.* |
-| from | `string`<br>`object` | `no` | A [runtime expression](#runtime-expressions), if any, used to filter and/or mutate the workflow/task input.  |
+| from | `string`<br>`object` | `no` | A [runtime expression](dsl.md#runtime-expressions), if any, used to filter and/or mutate the workflow/task input.  |
 
 #### Examples
 
@@ -1503,7 +1527,7 @@ When set, runtimes must validate output data against the defined schema, unless
 | Property | Type | Required | Description |
 |----------|:----:|:--------:|-------------|
 | schema | [`schema`](#schema) | `no` | The [`schema`](#schema) used to describe and validate output data.<br>*Even though the schema is not required, it is strongly encouraged to document it, whenever feasible.* |
-| as | `string`<br>`object` | `no` | A [runtime expression](#runtime-expressions), if any, used to filter and/or mutate the workflow/task output. |
+| as | `string`<br>`object` | `no` | A [runtime expression](dsl.md#runtime-expressions), if any, used to filter and/or mutate the workflow/task output. |
 
 #### Examples
 
@@ -1637,6 +1661,17 @@ minutes: 15
 seconds: 30
 ```
 
+### Endpoint
+
+Describes an enpoint.
+
+#### Properties
+
+| Property | Type | Required | Description |
+|----------|:----:|:--------:|-------------|
+| uri | `string` | `yes` | The endpoint's URI. |
+| authentication | `[authentication](#authentication)` | `no` | The authentication policy to use. |
+
 ### HTTP Response
 
 Describes an HTTP response.
diff --git a/dsl.md b/dsl.md
@@ -81,7 +81,7 @@ Workflows in the Serverless Workflow DSL can exist in several phases, each indic
 
 Additionally, the flow of execution within a workflow can be controlled using [directives*](dsl-reference.md#flow-directive), which provide instructions to the workflow engine on how to manage and handle specific aspects of workflow execution.
 
-**To learn more about flow directives and how they can be utilized to control the execution and behavior of workflows, please refer to [Flow Directives](dsl-reference.md#flow-directive).*
+\**To learn more about flow directives and how they can be utilized to control the execution and behavior of workflows, please refer to [Flow Directives](dsl-reference.md#flow-directive).*
 
 #### Components
 
@@ -102,14 +102,14 @@ The Serverless Workflow DSL defines several default [task](dsl-reference.md#task
 
 - [Call](dsl-reference.md#call), used to call services and/or functions.
 - [Do](dsl-reference.md#do), used to define one or more subtasks to perform in sequence.
-- [Fork](dsl-reference.md#fork), used to define one or more two subtasks to perform in parallel.
 - [Emit](dsl-reference.md#emit), used to emit [events](dsl-reference.md#event).
 - [For](dsl-reference.md#for), used to iterate over a collection of items, and conditionally perform a task for each of them.
+- [Fork](dsl-reference.md#fork), used to define one or more two subtasks to perform in parallel.
 - [Listen](dsl-reference.md#listen), used to listen for an [event](dsl-reference.md#event) or more.
 - [Raise](dsl-reference.md#raise), used to raise an [error](dsl-reference.md#error) and potentially fault the [workflow](dsl-reference.md#workflow).
 - [Run](dsl-reference.md#run), used to run a [container](dsl-reference.md#container-process), a [script](dsl-reference.md#script-process), a [shell](dsl-reference.md#shell-process) command or even another [workflow](dsl-reference.md#workflow-process). 
-- [Switch](dsl-reference.md#switch), used to dynamically select and execute one of multiple alternative paths based on specified conditions
 - [Set](dsl-reference.md#set), used to dynamically set or update the [workflow](dsl-reference.md#workflow)'s data during the its execution. 
+- [Switch](dsl-reference.md#switch), used to dynamically select and execute one of multiple alternative paths based on specified conditions
 - [Try](dsl-reference.md#try), used to attempt executing a specified [task](dsl-reference.md#task), and to handle any resulting [errors](dsl-reference.md#error) gracefully, allowing the [workflow](dsl-reference.md#workflow) to continue without interruption.
 - [Wait](dsl-reference.md#wait), used to pause or wait for a specified duration before proceeding to the next task.
 
@@ -138,7 +138,7 @@ A workflow begins with the first task defined.
 
 Once the task has been executed, different things can happen:
 
-- `continue`: the task ran to completion, and the next task, if any, should be executed. The task to run next is implictly the next in declaration order, or explicitly defined by the `then` property of the executed task. If the executed task is the last task, then the workflow's execution gracefully ends.
+- `continue`: the task ran to completion, and the next task, if any, should be executed. The task to run next is implicitly the next in declaration order, or explicitly defined by the `then` property of the executed task. If the executed task is the last task, then the workflow's execution gracefully ends.
 - `fault`: the task raised an uncaught error, which abruptly halts the workflow's execution and makes it transition to `faulted` [status phase](#status-phases).
 - `end`: the task explicitly and gracefully ends the workflow's execution. 
 
diff --git a/schema/workflow.yaml b/schema/workflow.yaml
@@ -1,3 +1,4 @@
+
 $id: https://serverlessworkflow.io/schemas/1.0.0-alpha1/workflow.yaml
 $schema: https://json-schema.org/draft/2020-12/schema
 description: Serverless Workflow DSL - Workflow Schema
@@ -369,37 +370,9 @@ $defs:
           event:
             type: object
             properties:
-              id:
-                type: string
-                description: The event's unique identifier
-              source:
-                description: Identifies the context in which an event happened
-                oneOf:
-                  - title: LiteralSource
-                    type: string
-                    format: uri-template
-                  - $ref: '#/$defs/runtimeExpression'
-              type:
-                type: string
-                description: This attribute contains a value describing the type of event related to the originating occurrence.
-              time:
-                oneOf:
-                  - title: LiteralTime
-                    type: string
-                    format: date-time
-                  - $ref: '#/$defs/runtimeExpression'
-              subject:
-                type: string
-              datacontenttype:
-                type: string
-                description: Content type of data value. This attribute enables data to carry any type of content, whereby format and encoding might differ from that of the chosen event format.
-              dataschema:
-                oneOf:
-                  - title: LiteralDataSchema
-                    type: string
-                    format: uri-template
-                  - $ref: '#/$defs/runtimeExpression'
-            required: [ source, type ]
+              with:
+                $ref: '#/$defs/eventProperties'
+                required: [ source, type ]
             additionalProperties: true
         required: [ event ]
   forTask:
@@ -852,6 +825,40 @@ $defs:
         $ref: '#/$defs/referenceableAuthenticationPolicy'
         description: The authentication policy to use.
     required: [ uri ]
+  eventProperties:
+    type: object
+    properties:
+      id:
+        type: string
+        description: The event's unique identifier
+      source:
+        description: Identifies the context in which an event happened
+        oneOf:
+          - title: LiteralSource
+            type: string
+            format: uri-template
+          - $ref: '#/$defs/runtimeExpression'
+      type:
+        type: string
+        description: This attribute contains a value describing the type of event related to the originating occurrence.
+      time:
+        oneOf:
+          - title: LiteralTime
+            type: string
+            format: date-time
+          - $ref: '#/$defs/runtimeExpression'
+      subject:
+        type: string
+      datacontenttype:
+        type: string
+        description: Content type of data value. This attribute enables data to carry any type of content, whereby format and encoding might differ from that of the chosen event format.
+      dataschema:
+        oneOf:
+          - title: LiteralDataSchema
+            type: string
+            format: uri-template
+          - $ref: '#/$defs/runtimeExpression'
+    additionalProperties: true
   eventConsumptionStrategy:
     type: object
     unevaluatedProperties: false
@@ -884,28 +891,8 @@ $defs:
     properties:
       with:
         title: WithEvent
-        type: object
+        $ref: '#/$defs/eventProperties'
         minProperties: 1
-        properties:
-          id:
-            type: string
-            description: The event's unique identifier
-          source:
-            type: string
-            description: Identifies the context in which an event happened
-          type:
-            type: string
-            description: This attribute contains a value describing the type of event related to the originating occurrence.
-          time:
-            type: string
-          subject:
-            type: string
-          datacontenttype:
-            type: string
-            description: Content type of data value. This attribute enables data to carry any type of content, whereby format and encoding might differ from that of the chosen event format.
-          dataschema:
-            type: string
-        additionalProperties: true
         description: An event filter is a mechanism used to selectively process or handle events based on predefined criteria, such as event type, source, or specific attributes.
       correlate:
         type: object
