Add explanation for additional properties (#343)

* Add explanation for additional properties

Signed-off-by: Tihomir Surdilovic <[email protected]>

* Update specification.md

Co-authored-by: Ricardo Zanini <[email protected]>

Co-authored-by: Ricardo Zanini <[email protected]>

Author: tsurdilo

roadmap/README.md

@@ -25,6 +25,7 @@ _Status description:_
 | ✔️| Replaced SubFlow state with subflow action type | [spec doc](../specification.md) |
 | ✔️| Add workflow `dataInputSchema` property | [spec doc](../specification.md) |
 | ✔️| Rename switch state `default` to `defaultCondition` to avoid keyword conflicts for SDK's | [spec doc](../specification.md) |
+| ✔️| Add description of additional properties | [spec doc](../specification.md) |
 | 🚩 | Workflow invocation bindings |  |
 | 🚩 | CE Subscriptions & Discovery |  |
 | 🚩 | Error types | [issue](https://github.com/serverlessworkflow/specification/issues/200) | 

specification.md

@@ -1394,7 +1394,7 @@ definition "id" must be a constant value.
 | [functions](#Function-Definition) | Workflow function definitions. Can be either inline function definitions (if array) or URI pointing to a resource containing json/yaml function definitions (if string) | array or string| no |
 | [retries](#Retry-Definition) | Workflow retries definitions. Can be either inline retries definitions (if array) or URI pointing to a resource containing json/yaml retry definitions (if string) | array or string| no |
 | [states](#State-Definition) | Workflow states | array | yes |
-| [metadata](#Workflow-Metadata) | Metadata information| object | no |
+| [metadata](#Workflow-Metadata) | Metadata information | object | no |
 
 <details><summary><strong>Click to view example definition</strong></summary>
 <p>
@@ -1591,6 +1591,52 @@ This allows you to explicitly model workflows where an instance should be kept a
 
 You can reference the [specification examples](#Examples) to see the `keepActive` property in action.
 
+#### Additional Properties
+
+Specifying additional properties, namely properties which are not defined by the specification
+are only allowed in the [Workflow Definition](#Workflow-Definition-Structure). 
+Additional properties serve the same purpose as [Workflow Metadata](#Workflow-Metadata).
+They allow you to enrich the workflow definition with custom information. 
+
+Additional properties, just like workflow metadata, should not affect workflow execution. 
+Implementations may choose to use additional properties or ignore them.
+
+It is recommended to use workflow metadata instead of additional properties in the workflow definition.
+
+Let's take a look at an example of additional properties:
+
+```json
+{  
+  "id": "myworkflow",
+  "version": "1.0",
+  "name": "My Test Workflow",
+  "start": "My First State",
+  "loglevel": "Info",
+  "environment": "Production",
+  "category": "Sales",
+  "states": [ ... ]
+}
+```
+
+In this example, we specify the `loglevel`, `environment`, and `category` additional properties.
+
+Note the same can be also specified using workflow metadata, which is the preferred approach:
+
+```json
+{
+  "id": "myworkflow",
+  "version": "1.0",
+  "name": "Py Test Workflow",
+  "start": "My First State",
+  "metadata": {
+    "loglevel": "Info",
+    "environment": "Production",
+    "category": "Sales"
+  },
+  "states": [ ... ]
+}
+```
+
 #### ExecTimeout Definition
 
 | Parameter | Description | Type | Required |