cncf
/
wg-serverless
mirror of https://github.com/cncf/wg-serverless.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Metadata definition for core workflow, events, functions, and states … (#193) 

* Metadata definition for core workflow, events, functions, and states definitions

* updating for new state
This commit is contained in:
Tihomir Surdilovic 2020-03-20 23:59:09 -04:00 committed by GitHub
parent 638c701af6
commit 43bfd6fb63
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 138 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
workflow/spec/schema/serverless-workflow-schema.json
View File

@ -45,6 +45,9 @@
"format": "uri",
"description": "URI to JSON Schema that workflow data output adheres to"
},
"metadata": {
"$ref": "#/definitions/metadata"
},
"events": {
"type": "array",
"description": "Workflow event definitions. Defines events that can be consumed or produced",
@ -121,6 +124,10 @@
"states"
],
"definitions": {
"metadata": {
"type": "object",
"description": "Metadata information"
},
"transition": {
"type": "object",
"properties": {
@ -177,6 +184,9 @@
"correlationToken": {
"type": "string",
"description": "Context attribute name of the CloudEvent which value is to be used for event correlation"
},
"metadata": {
"$ref": "#/definitions/metadata"
}
},
"required": [
@ -275,6 +285,9 @@
"type": {
"type": "string",
"description": "Type of function to implement. Can be defined by implementations"
},
"metadata": {
"$ref": "#/definitions/metadata"
}
},
"required": [
@ -416,6 +429,9 @@
"type": "string",
"format": "uri",
"description": "URI to JSON Schema that state data output adheres to"
},
"metadata": {
"$ref": "#/definitions/metadata"
}
},
"oneOf": [
@ -510,6 +526,9 @@
"end": {
"$ref": "#/definitions/end",
"description": "State end definition"
},
"metadata": {
"$ref": "#/definitions/metadata"
}
},
"oneOf": [
@ -604,6 +623,9 @@
"type": "string",
"format": "uri",
"description": "URI to JSON Schema that state data output adheres to"
},
"metadata": {
"$ref": "#/definitions/metadata"
}
},
"oneOf": [
@ -691,6 +713,9 @@
"type": "string",
"format": "uri",
"description": "URI to JSON Schema that state data output adheres to"
},
"metadata": {
"$ref": "#/definitions/metadata"
}
},
"oneOf": [
@ -784,6 +809,9 @@
"type": "string",
"format": "uri",
"description": "URI to JSON Schema that state data output adheres to"
},
"metadata": {
"$ref": "#/definitions/metadata"
}
},
"oneOf": [
@ -862,6 +890,9 @@
"type": "string",
"format": "uri",
"description": "URI to JSON Schema that state data output adheres to"
},
"metadata": {
"$ref": "#/definitions/metadata"
}
},
"oneOf": [
@ -927,6 +958,9 @@
"type": "string",
"format": "uri",
"description": "URI to JSON Schema that state data output adheres to"
},
"metadata": {
"$ref": "#/definitions/metadata"
}
},
"oneOf": [
@ -1068,6 +1102,9 @@
"type": "string",
"format": "uri",
"description": "URI to JSON Schema that state data output adheres to"
},
"metadata": {
"$ref": "#/definitions/metadata"
}
},
"oneOf": [
@ -1166,6 +1203,9 @@
"end": {
"$ref": "#/definitions/end",
"description": "State end definition"
},
"metadata": {
"$ref": "#/definitions/metadata"
}
},
"oneOf": [

100
workflow/spec/spec.md
View File

@ -24,6 +24,7 @@ This document is a working draft.
- [Workflow Definition](#Workflow-Definition)
- [Workflow Data](#Workflow-Data)
- [Workflow Error Handling](#Workflow-Error-Handling)
- [Workflow Metadata](#Workflow-Metadata)
- [Extending](#Extending)
- [Use Cases](#Use-Cases)
- [Examples](#Examples)
@ -139,6 +140,7 @@ As mentioned, implementation compliance is based on the workflow definition lang
| [functions](#Function-Definition) | Workflow functions | array | no |
| [states](#State-Definition) | Workflow states | array | yes |
| [extensions](#Extending) | Workflow custom extensions | array | no |
| [metadata](#Workflow-Metadata) | Metadata information| object | no |
<details><summary><strong>Click to view JSON Schema</strong></summary>
<p>
@ -253,6 +255,9 @@ As mentioned, implementation compliance is based on the workflow definition lang
"items": {
"type": "object"
}
},
"metadata": {
"$ref": "#/definitions/metadata"
}
},
"required": ["id", "name", "version", "startsAt", "states"]
@ -284,6 +289,7 @@ Since function definitions are reusable, their data input parameters are defined
| name | Unique function name | string | yes |
| resource | Function resource (URI) | string | yes |
| type | Function type. Can be defined by implementations. | string | no |
| [metadata](#Workflow-Metadata) | Metadata information| object | no |
<details><summary><strong>Click to view JSON Schema</strong></summary>
@ -303,6 +309,9 @@ Since function definitions are reusable, their data input parameters are defined
"type": {
"type": "string",
"description": "Type of function to implement. Can be defined by implementations"
},
"metadata": {
"$ref": "#/definitions/metadata"
}
},
"required": ["name", "resource"]
@ -319,6 +328,7 @@ Since function definitions are reusable, their data input parameters are defined
| source | CloudEvent source | string | yes |
| type | CloudEvent type | string | yes |
| correlationToken | Context attribute name of the CloudEvent which value is to be used for event correlation | string | no |
| [metadata](#Workflow-Metadata) | Metadata information| object | no |
<details><summary><strong>Click to view JSON Schema</strong></summary>
@ -341,6 +351,9 @@ Since function definitions are reusable, their data input parameters are defined
"correlationToken": {
"type": "string",
"description": "Path used for event correlation."
},
"metadata": {
"$ref": "#/definitions/metadata"
}
},
"required": ["name", "source", "type"]
@ -454,6 +467,7 @@ Following is a detailed decription of each of the defined states:
| [retry](#workflow-retrying) | States retry definitions | array | no |
| [onError](#Workflow-Error-Handling) | States error handling definitions | array | no |
| [end](#End-Definition) | Is this state an end state | object | no |
| [metadata](#Workflow-Metadata) | Metadata information| object | no |
<details><summary><strong>Click to view JSON Schema</strong></summary>
<p>
@ -530,6 +544,9 @@ Following is a detailed decription of each of the defined states:
"end": {
"$ref": "#/definitions/end",
"description": "State end definition"
},
"metadata": {
"$ref": "#/definitions/metadata"
}
},
"oneOf": [
@ -918,6 +935,7 @@ Defines a transition from point A to point B in the serverless workflow. For mor
| [transition](#Transitions) | Next transition of the workflow after all the actions have been performed | string | yes (if end is not defined) |
| [dataInputSchema](#Information-Passing-Between-States) | URI to JSON Schema that state data input adheres to | string | no |
| [dataOutputSchema](#Information-Passing-Between-States) | URI to JSON Schema that state data output adheres to | string | no |
| [metadata](#Workflow-Metadata) | Metadata information| object | no |
<details><summary><strong>Click to view JSON Schema</strong></summary>
@ -990,6 +1008,9 @@ Defines a transition from point A to point B in the serverless workflow. For mor
"type": "string",
"format": "uri",
"description": "URI to JSON Schema that state data output adheres to"
},
"metadata": {
"$ref": "#/definitions/metadata"
}
},
"oneOf": [
@ -1034,6 +1055,7 @@ Once all actions have been performed, a transition to another state can occur.
| default |Next transition of the workflow if there is no match for any choices | object | yes (if end is not defined) |
| [dataInputSchema](#Information-Passing-Between-States) | URI to JSON Schema that state data input adheres to | string | no |
| [dataOutputSchema](#Information-Passing-Between-States) | URI to JSON Schema that state data output adheres to | string | no |
| [metadata](#Workflow-Metadata) | Metadata information| object | no |
<details><summary><strong>Click to view JSON Schema</strong></summary>
@ -1097,6 +1119,9 @@ Once all actions have been performed, a transition to another state can occur.
"type": "string",
"format": "uri",
"description": "URI to JSON Schema that state data output adheres to"
},
"metadata": {
"$ref": "#/definitions/metadata"
}
},
"oneOf": [
@ -1328,6 +1353,7 @@ There are four types of choices defined:
| [transition](#Transitions) |Next transition of the workflow after the delay | string | yes (if end is not defined) |
| [dataInputSchema](#Information-Passing-Between-States) | URI to JSON Schema that state data input adheres to | string | no |
| [dataOutputSchema](#Information-Passing-Between-States) | URI to JSON Schema that state data output adheres to | string | no |
| [metadata](#Workflow-Metadata) | Metadata information| object | no |
<details><summary><strong>Click to view JSON Schema</strong></summary>
@ -1382,6 +1408,9 @@ There are four types of choices defined:
"type": "string",
"format": "uri",
"description": "URI to JSON Schema that state data output adheres to"
},
"metadata": {
"$ref": "#/definitions/metadata"
}
},
"oneOf": [
@ -1424,6 +1453,7 @@ Delay state waits for a certain amount of time before transitioning to a next st
| [transition](#Transitions) |Next transition of the workflow after all branches have completed execution | string | yes (if end is not defined) |
| dataInputSchema | URI to JSON Schema that state data input adheres to | string | no |
| dataOutputSchema | URI to JSON Schema that state data output adheres to | string | no |
| [metadata](#Workflow-Metadata) | Metadata information| object | no |
<details><summary><strong>Click to view JSON Schema</strong></summary>
@ -1490,6 +1520,9 @@ Delay state waits for a certain amount of time before transitioning to a next st
"type": "string",
"format": "uri",
"description": "URI to JSON Schema that state data output adheres to"
},
"metadata": {
"$ref": "#/definitions/metadata"
}
},
"oneOf": [
@ -1621,6 +1654,7 @@ Parallel state must wait for all branches which have this property set to "true"
| [transition](#Transitions) |Next transition of the workflow after subflow has completed | string | yes (if end is not defined) |
| dataInputSchema | URI to JSON Schema that state data input adheres to | string | no |
| dataOutputSchema | URI to JSON Schema that state data output adheres to | string | no |
| [metadata](#Workflow-Metadata) | Metadata information| object | no |
<details><summary><strong>Click to view JSON Schema</strong></summary>
@ -1680,6 +1714,9 @@ Parallel state must wait for all branches which have this property set to "true"
"type": "string",
"format": "uri",
"description": "URI to JSON Schema that state data output adheres to"
},
"metadata": {
"$ref": "#/definitions/metadata"
}
},
"oneOf": [
@ -1737,6 +1774,7 @@ If this property is set to false, data access to parent's workflow should not be
| [transition](#Transitions) | Next transition of the workflow after subflow has completed | string | yes (if end is set to false) |
| dataInputSchema | URI to JSON Schema that state data input adheres to | string | no |
| dataOutputSchema | URI to JSON Schema that state data output adheres to | string | no |
| [metadata](#Workflow-Metadata) | Metadata information| object | no |
<details><summary><strong>Click to view JSON Schema</strong></summary>
@ -1783,6 +1821,9 @@ If this property is set to false, data access to parent's workflow should not be
"type": "string",
"format": "uri",
"description": "URI to JSON Schema that state data output adheres to"
},
"metadata": {
"$ref": "#/definitions/metadata"
}
},
"oneOf": [
@ -1987,6 +2028,7 @@ This allows you to test if your workflow behaves properly for cases when there a
| [transition](#Transitions) | Next transition of the workflow after state has completed | string | yes (if end is not defined) |
| dataInputSchema | URI to JSON Schema that state data input adheres to | string | no |
| dataOutputSchema | URI to JSON Schema that state data output adheres to | string | no |
| [metadata](#Workflow-Metadata) | Metadata information| object | no |
<details><summary><strong>Click to view JSON Schema</strong></summary>
@ -2112,6 +2154,9 @@ This allows you to test if your workflow behaves properly for cases when there a
"type": "string",
"format": "uri",
"description": "URI to JSON Schema that state data output adheres to"
},
"metadata": {
"$ref": "#/definitions/metadata"
}
},
"oneOf": [
@ -2359,6 +2404,7 @@ defined in the orders array of its data input.
| [dataOutputSchema](#Information-Passing-Between-States) | URI to JSON Schema that state data output adheres to | string | no |
| [transition](#Transitions) | Next transition of the workflow after callback event has been received | string | yes |
| [end](#End-Definition) | Is this state an end state | object | no |
| [metadata](#Workflow-Metadata) | Metadata information| object | no |
<details><summary><strong>Click to view JSON Schema</strong></summary>
<p>
@ -2435,6 +2481,9 @@ defined in the orders array of its data input.
"end": {
"$ref": "#/definitions/end",
"description": "State end definition"
},
"metadata": {
"$ref": "#/definitions/metadata"
}
},
"oneOf": [
@ -2756,7 +2805,7 @@ Implementers should decide how to handle data-base transitions which return fals
The default should be that if this happens workflow execution should halt and a detailed message
on why the transition failed should be provided.
#### Workflow Data
### Workflow Data
Serverless Workflow data is represented in [JSON](https://www.json.org/json-en.html) format.
Flow of data during workflow execution can be divided into:
@ -3278,7 +3327,7 @@ In order to define the structure of expected workflow data output you can use th
that describes the expected workflow data output. This can be used for documentation purposes or implementations may
decide to strictly enforce it.
#### Workflow Error Handling
### Workflow Error Handling
Any state can encounter runtime errors. Errors can arise from state failures such as exeptions thrown during function
execution, network errors, or errors in the workflow definition (incorrect paths for example).
@ -3516,6 +3565,53 @@ the "afterFunctionErrorState" state. In case of any other errors, they will be r
If those errors occur after two max 2 retries, the onError definition states that workflow should transition to the
"afterAnyOtherErrorState" state.
### Workflow Metadata
Metdata enables you to enrich the serverless workflow model with information beyond its core definitions.
It is inteded to be used by clients such as tools and libraries, as well as users that find this information relevant.
Metadata should not affect workflow execution. Implementations may chose to use metadata information or ignore it.
Note however that using metadata to control workflow execution can lead to vendor-locked implementations which do comply with the main goals of this specification, which is to be completely vendor-neutral.
Metadata includes key/value pairs (string types). Both keys and values are completely arbitrary and non-identifying.
Metadata can be added to:
- [Core Workflow definition](#Workflow-Definition)
- [Function definitions](#Function-Definition)
- [Event definitions](#Event-Definition)
- [State definitions](#State-Definition)
Here is an example of metadata attached to the core workflow definition:
```json
{
"id": "processSalesOrders",
"name": "Process Sales Orders",
"version": "1.0",
"startsAt": "NewOrder",
"metadata": {
"loglevel": "Info",
"environment": "Production",
"category": "Sales",
"giturl": "github.com/myproject",
"author": "Author Name",
"team": "Team Name",
...
},
"states": [
...
]
}
```
Some other examples of information that could be recorded in metadata are:
- UI tooling information such as sizing or scaling factors.
- Build, release, or image information such as timestamps, release Ids, git branches, PR numbers, etc.
- Logging, Monitoring, Analytics, or Audit repository information.
- Labels used for organizing/indexing purposes, such as "release" "stable", "track", "daily", etc.
## Extending
Serverless Workflows are build with extensibility in mind. The extension mechanism allows