[Fix #742] Ricardos comments

fjtirado · fjtirado · commit 77c77b2122b9 · 2024-02-22T17:09:12.000+01:00
Signed-off-by: Francisco Javier Tirado Sarti &lt;ftirados@redhat.com&gt;
diff --git a/specification.md b/specification.md
@@ -643,8 +643,8 @@ a workflow with a single event state and show how data filters can be combined.
 
 ```json
 {
-    "id": "GreetCustomersWorkflow",
-    "name": "Greet Customers when they arrive",
+    "name": "GreetCustomersWorkflow",
+    "description": "Greet Customers when they arrive",
     "version": "1.0.0",
     "specVersion": "0.8",
     "start": "WaitForCustomerToArrive",
@@ -1910,16 +1910,16 @@ we can use this expression in the workflow "version" parameter:
 
 ```json
 {
-   "id": "MySampleWorkflow",
-   "name": "Sample Workflow",
+   "name": "MySampleWorkflow",
+   "description": "Sample Workflow",
    "version": "${ .inputVersion }",
    "specVersion": "0.8"
 }
 ```
 
 which would set the workflow version to "1.0.0".
-Note that the workflow "id" property value is not allowed to use an expression. The workflow
-definition "id" must be a constant value.
+Note that the workflow "name" property value is not allowed to use an expression. The workflow
+definition "name" must be a constant value.
 
 ### Workflow Definition Structure
 
@@ -1962,10 +1962,9 @@ definition "id" must be a constant value.
 
 ```json
 {
-   "id": "sampleWorkflow",
+   "name": "sampleWorkflow",
    "version": "1.0.0",
    "specVersion": "0.8",
-   "name": "Sample Workflow",
    "description": "Sample Workflow",
    "start": "MyStartingState",
    "states": [],
@@ -1980,10 +1979,9 @@ definition "id" must be a constant value.
 <td valign="top">
 
 ```yaml
-id: sampleWorkflow
+name: sampleWorkflow
 version: '1.0.0'
 specVersion: '0.8'
-name: Sample Workflow
 description: Sample Workflow
 start: MyStartingState
 states: []
@@ -2006,18 +2004,13 @@ Following figure describes the main workflow definition blocks.
 <img src="media/spec/workflowdefinitionblocks.png" height="300px" alt="Serverless Workflow Definitions Blocks"/>
 </p>
 
-The `id` property defines the unique, domain-specific workflow identifier, for example "orders", "payment", etc.
-
-The `key` property defines the unique, domain-specific workflow identifier.
-It can be used when the `id` property is auto-generated by a content-management system for example.
-In these cases, you can specify the `key` property to be the domain-specific identifier of the workflow definition.
-The `id` and `key` properties are mutually exclusive, meaning you cannot define both.
+The required `name` property  defines the unique workflow definition identifier, for example "orders", "payment", etc.
 
-The `name` property is the workflow logical name.
+The optional `key` property is an expression that evaluates to a domain related, unique running workflow instance identifier, for example "orders-1", "orders-2"...
 
-The `description` property can be used to give further information about the workflow.
+The `description` property might be used to give further information about the workflow.
 
-The `version` property can be used to provide a specific workflow version. It must use the [semantic versioning](https://semver.org/) format.
+The `version` property can be used to provide a specific workflow version. It must use the [semantic versioning](https://semver.org/) format.If not specified, "latest" is assumed. 
 
 The `annotations` property defines a list of helpful terms describing the workflows intended purpose, subject areas, or other important qualities,
 for example "machine learning", "monitoring", "networking", etc
@@ -2168,10 +2161,9 @@ Here is an example of using external resource for function definitions:
 
 ```json
 {
-   "id": "sampleWorkflow",
+   "name": "sampleWorkflow",
    "version": "1.0.0",
    "specVersion": "0.8",
-   "name": "Sample Workflow",
    "description": "Sample Workflow",
    "start": "MyStartingState",
    "functions": "http://myhost:8080/functiondefs.json",
@@ -2205,10 +2197,9 @@ Here is an example of using external resource for event definitions:
 
 ```json
 {
-   "id": "sampleWorkflow",
+   "name": "sampleWorkflow",
    "version": "1.0.0",
    "specVersion": "0.8",
-   "name": "Sample Workflow",
    "description": "Sample Workflow",
    "start": "MyStartingState",
    "events": "http://myhost:8080/eventsdefs.json",
@@ -3149,7 +3140,6 @@ and our workflow is defined as:
 
 ```json
 {
-  "id": "sendConfirmWorkflow",
   "name": "SendConfirmationForCompletedOrders",
   "version": "1.0.0",
   "specVersion": "0.8",
@@ -3186,7 +3176,6 @@ and our workflow is defined as:
 <td valign="top">
 
 ```yaml
-id: sendConfirmWorkflow
 name: SendConfirmationForCompletedOrders
 version: '1.0.0'
 specVersion: '0.8'
@@ -4031,9 +4020,9 @@ multiple other workflow definitions.
 <img src="media/spec/subflowstateref.png" height="350px" alt="Referencing reusable workflow via SubFlow actions"/>
 </p>
 
-Reusable workflows are referenced by their `id` property via the SubFlow action `workflowId` parameter.
+Reusable workflows are referenced by their `name` property via the SubFlow action `workflowId` parameter.
 
-For the simple case, `subFlowRef` can be a string containing the `id` of the sub-workflow to invoke.
+For the simple case, `subFlowRef` can be a string containing the `name` of the sub-workflow to invoke.
 If you want to specify other parameters then a [subFlowRef](#SubFlowRef-Definition) should be provided instead.
 
 Each referenced workflow receives the SubFlow actions data as workflow data input.
@@ -4200,19 +4189,19 @@ should not fail workflow execution.
 
 `SubFlowRef` definition can have two types, namely `string` or `object`.
 
-If `string` type, it defines the unique id of the sub-workflow to be invoked.
-This short-hand definition can be used if sub-workflow lookup is done only by its `id`
+If `string` type, it defines the unique name of the sub-workflow to be invoked.
+This short-hand definition can be used if sub-workflow lookup is done only by its `name`
 property and not its `version` property.
 
 ```json
-"subFlowRef": "mySubFlowId"
+"subFlowRef": "mySubFlowName"
 ```
 
 If you need to define the `version` properties, you can use its `object` type:
 
 | Parameter | Description | Type | Required |
 | --- | --- | --- | --- |
-| workflowId | Sub-workflow unique id | string | yes |
+| workflowId | Sub-workflow unique name | string | yes |
 | version | Sub-workflow version | string | no |
 | invoke | Specifies if the subflow should be invoked `sync` or `async`. Default is `sync` | enum | no |
 | onParentComplete | If `invoke` is `async`, specifies if subflow execution should `terminate` or `continue` when parent workflow completes. Default is `terminate` | enum | no |
@@ -4249,8 +4238,8 @@ version: '2.0.0'
 
 </details>
 
-The `workflowId` property define the unique ID of the sub-workflow to be invoked.
-Usually, the workflow id should not be the same id of the workflow where the action is defined. Otherwise, it may occur undesired recurring calls to the same workflow.
+The `workflowId` property define the unique name of the sub-workflow to be invoked.
+The workflow id should not be the same name  of the workflow where the action is defined. Otherwise, it may occur undesired recurring calls to the same workflow.
 
 The `version` property defined the unique version of the sub-workflow to be invoked.
 If this property is defined, runtimes should match both the `id` and the `version` properties
@@ -4707,7 +4696,7 @@ actions:
 
 Each branch receives the same copy of the Parallel state's data input.
 
-A branch can define actions that need to be executed. For the [`SubFlowRef`](#SubFlowRef-Definition) action, the workflow id should not be the same id of the workflow where the branch is defined. Otherwise, it may occur undesired recurring calls to the same workflow.
+A branch can define actions that need to be executed. For the [`SubFlowRef`](#SubFlowRef-Definition) action, the workflow name should not be the same name of the workflow where the branch is defined. Otherwise, it may occur undesired recurring calls to the same workflow.
 
 
 The `timeouts` property can be used to set branch specific timeout settings. Parallel state branches can set the
@@ -4993,7 +4982,7 @@ If the end definition is of type `object`, it has the following structure:
 | terminate | If `true`.  terminates workflow instance execution | boolean | no |
 | produceEvents | Array of [producedEvent](#ProducedEvent-Definition) definitions. Defines events that should be produced. | array | no |
 | [compensate](#Workflow-Compensation) | If set to `true`, triggers workflow compensation before workflow execution completes. Default is `false` | boolean | no |
-| [continueAs](#continuing-as-a-new-execution) | Defines that current workflow execution should stop, and execution should continue as a new workflow instance of the provided id | string or object | no |
+| [continueAs](#continuing-as-a-new-execution) | Defines that current workflow execution should stop, and execution should continue as a new workflow instance of the provided name | string or object | no |
 
 <details><summary><strong>Click to view example definition</strong></summary>
 <p>
@@ -5058,7 +5047,7 @@ The [continueAs](#Continuing-as-a-new-Execution) property defines that the curre
 and worklow execution should continue as a new instance of a new workflow.
 When defined, it should be assumed that `terminate` is `true`. If `continueAs` is defined, and `terminate` is explicitly
 set to `false`, runtimes should report this to users. Producing events, and compensation should still be performed (if defined)
-before the workflow execution is stopped, and continued as a new workflow instance with the defined workflow id.
+before the workflow execution is stopped, and continued as a new workflow instance with the defined workflow name.
 
 ##### ProducedEvent Definition
 
@@ -5152,10 +5141,10 @@ Let's take a look at an example of additional properties:
 
 ```json
 {
-  "id": "myworkflow",
+  "name": "myworkflow",
   "version": "1.0.0",
   "specVersion": "0.8",
-  "name": "My Test Workflow",
+  "description": "My Test Workflow",
   "start": "My First State",
   "loglevel": "Info",
   "environment": "Production",
@@ -5170,10 +5159,10 @@ Note the same can be also specified using workflow metadata, which is the prefer
 
 ```json
 {
-  "id": "myworkflow",
+  "name": "myworkflow",
   "version": "1.0.0",
   "specVersion": "0.8",
-  "name": "Py Test Workflow",
+  "description": "Py Test Workflow",
   "start": "My First State",
   "metadata": {
     "loglevel": "Info",
@@ -5599,7 +5588,7 @@ To give an example, let's say that in our workflow definition we define the time
 
 ```json
 {
-   "id": "testWorkflow",
+   "name": "testWorkflow",
    ...
    "timeouts": {
      ...
@@ -6109,23 +6098,23 @@ likely to be forced to stop before reaching its completion. This can result in u
 mission-critical workflows.
 
 For those cases, the Serverless Workflow DSL provides a way to explicitly define stopping the current workflow
-instance execution, and starting a new one (for the same workflow id or a different one).
+instance execution, and starting a new one (for the same workflow name or a different one).
 This can be done via the [end definitions](#end-definition) `continueAs` property.
 
 The end definitions `continueAs` can be either of type `string` or `object`.
-If string type, it contains the unique workflow id of the workflow that the execution should continue as, for example:
+If string type, it contains the unique workflow name of the workflow that the execution should continue as, for example:
 
 
 ```json
 { 
   "end": {
-    "continueAs": "myworkflowid"
+    "continueAs": "myworkflowname"
   }
 }
 ```
 
 Defining this should stop the current workflow execution, and continue execution as a new workflow instance of the 
-workflow which defines the workflow id of "myworkflowid". The state data where this is define should 
+workflow which defines the workflow name of "myworkflowbane". The state data where this is define should 
 become the workflow data input of the workflow that is continuing the current workflow execution.
 
 Note that any defined `produceEvents` and `compensate` definitions should be honored before `continueAs` is applied.
@@ -6134,7 +6123,7 @@ If `object` type, the `continueAs` property has the following properties:
 
 | Parameter | Description | Type | Required |
 | --- | --- | --- | --- |
-| workflowId | Unique id of the workflow to continue execution as. | string | yes |
+| workflowId | Unique name of the workflow to continue execution as. | string | yes |
 | version | Version of the workflow to continue execution as. | string | no |
 | data | If string type, a workflow expression which selects parts of the states data output to become the workflow data input of continued execution. If object type, a custom object to become the workflow data input of the continued execution. | string or object | no |
 | [`workflowExecTimeout`](#Workflow-Timeouts) | Workflow execution timeout to be used by the workflow continuing execution. Overwrites any specific settings set by that workflow. | string or object | no |
@@ -6149,7 +6138,7 @@ in workflow states [Action](#Action-Definition) definitions.
 
 Just like "parent" workflows, sub-workflow can also be long-running, and can run into the same type of runtime/serverless platform
 limitations as previously discussed. As such they can also use `continueAs` to stop their current execution and continue it as 
-a new one of the same or different workflow id.
+a new one of the same or different workflow name.
 
 Note that when a sub-workflow is invoked it can produce a result that is then merged into the parent workflow state data.
 This may bring up a question as to what happens when a sub-workflow calls `continueAs` in terms of what is returned as
@@ -6315,8 +6304,8 @@ Here is an example of metadata attached to the core workflow definition:
 
 ```json
 {
-  "id": "processSalesOrders",
-  "name": "Process Sales Orders",
+  "name": "processSalesOrders",
+  "description": "Process Sales Orders",
   "version": "1.0.0",
   "specVersion": "0.8",
   "start": "MyStartingState",
@@ -6351,8 +6340,8 @@ Implementations may use this keyword to give access to any relevant information
 ```json
 
 {
-  "id": "processSalesOrders",
-  "name": "Process Sales Orders",
+  "name": "processSalesOrders",
+  "description": "Process Sales Orders",
   "version": "1.0.0",
   "specVersion": "0.8",
   "start": "my-starting-state",
