Merge pull request #696 from fjtirado/dataOutputSchema

outputDataSchema addition

Author: cdavernas

roadmap/README.md

@@ -45,6 +45,7 @@ _Status description:_
 | ✏️️| Add SDKs for more languages (Python, PHP, Rust, etc) |   |
 | ✏️️| Add more samples  |   |
 | ✏️️| Enforce SemVer `version`  |   |
+| ✏️️| Add `dataOutputSchema`  |   |
 
 ## <a name="v08"></a> Released version v0.8
 

schema/workflow.json

@@ -39,42 +39,10 @@
       "additionalItems": false
     },
     "dataInputSchema": {
-      "oneOf": [
-        {
-          "type": "string",
-          "description": "URI of the JSON Schema used to validate the workflow data input",
-          "minLength": 1
-        },
-        {
-          "type": "object",
-          "description": "Workflow data input schema definition",
-          "properties": {
-            "schema": {
-              "oneof": [
-                {
-                  "type": "string",
-                  "description": "URI of the JSON Schema used to validate the workflow data input",
-                  "minLength": 1
-                },
-                {
-                  "type": "object",
-                  "description": "The JSON Schema object used to validate the workflow data input",
-                  "$schema": "http://json-schema.org/draft-07/schema#"
-                }
-              ]
-            },
-            "failOnValidationErrors": {
-              "type": "boolean",
-              "default": true,
-              "description": "Determines if workflow execution should continue if there are validation errors"
-            }
-          },
-          "additionalProperties": false,
-          "required": [
-            "schema"
-          ]
-        }
-      ]
+      "$ref": "#/definitions/validationSchema"
+    },
+    "dataOutputSchema": {
+      "$ref": "#/definitions/validationSchema"
     },
     "secrets": {
       "$ref": "secrets.json#/secrets"
@@ -1899,6 +1867,44 @@
       },
       "additionalProperties": false,
       "required": []
+    },
+    "validationSchema" :  {
+      "oneOf": [
+        {
+          "type": "string",
+          "description": "URI of the JSON Schema used to validate the workflow",
+          "minLength": 1
+        },
+        {
+          "type": "object",
+          "description": "Workflow data input schema definition",
+          "properties": {
+            "schema": {
+              "oneof":[
+                {
+                  "type": "string",
+                  "description": "URI of the JSON Schema used to validate the workflow",
+                  "minLength": 1
+                },
+                {
+                  "type": "object",
+                  "description": "The JSON Schema object used to validate the workflow",
+                  "$schema": "http://json-schema.org/draft-07/schema#"
+                }
+              ]
+            },
+            "failOnValidationErrors": {
+              "type": "boolean",
+              "default": true,
+              "description": "Determines if error should be thrown if there are validation errors"
+            }
+          },
+          "additionalProperties": false,
+          "required": [
+            "schema"
+          ]
+        }
+      ]
     }
   }
 }

specification.md

@@ -1769,6 +1769,7 @@ definition "id" must be a constant value.
 | version | Workflow version. MUST respect the [semantic versioning](https://semver.org/) format | string | no |
 | annotations | List of helpful terms describing the workflows intended purpose, subject areas, or other important qualities | array | no |
 | dataInputSchema | Used to validate the workflow data input against a defined JSON Schema| string or object | no |
+| dataOutputSchema | Used to validate the workflow data output against a defined JSON Schema| string or object | no |
 | [constants](#Workflow-Constants) | Workflow constants | string or object | no |
 | [secrets](#Workflow-Secrets) | Workflow secrets | string or array | no |
 | [start](#Start-Definition) | Workflow start definition | string or object | no |
@@ -1859,22 +1860,33 @@ The `version` property can be used to provide a specific workflow version. It mu
 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
 
-The `dataInputSchema` property can be used to validate the workflow data input against a defined JSON Schema.
-This check should be done before any states are executed. `dataInputSchema` can have two different types.
-If it is an object type it has the following definition:
+The `dataInputSchema` and `dataOutputSchema` properties can be used to validate input and output data against a defined JSON Schema.
+
+The `dataInputSchema` property validates the [workflow data input](#Workflow-Data-Input). Validation should be performed before any states are executed. In case of
+a start [Event state](#Event-state) the input schema is ignored, if present. The `failOnValidationErrors` property  determines if workflow execution should continue in case of validation errors. 
+
+The `dataOutputSchema` property validates the [Workflow data output](#workflow-data-output). Validation is performed on the output of the workflow execution. 
+The `failOnValidationErrors` property determines what should be done when the workflow output does not match the provided schema. 
+If `failOnValidationErrors` is true, an error should be thrown. If executed within a subprocess, that error can be be handled by the parent workflow. 
+If `failOnValidationErrors` is false, the error should not be propagated. It is up to the implementor to warn the user about that fact. For example, printing a log. 
+
+Both properties can be expressed as object or string type. 
+
+If using object type, their `schema` property might be an URI, which points to the JSON schema used to validate the workflow data input, or it might be the JSON schema object. `failOnValidationErrors` is optional, default value is `true`.
+
+Example for Json schema reference
 
 ```json
 "dataInputSchema": {
-   "schema": "URL_to_json_schema",
+   "schema": "URI to json schema",
    "failOnValidationErrors": false
 }
 ```
 
-It's `schema` property can be an URI, which points to the JSON schema used to validate the workflow data input, or it can be the JSON schema object.
-If it's a JSON schema object, it has the following definition:
+Example for Json schema included in the workflow file
 
 ```json
-"dataInputSchema": {
+"dataOutputSchema": {
    "schema": {
      "title": "MyJSONSchema",
      "properties":{
@@ -1886,22 +1898,18 @@ If it's a JSON schema object, it has the following definition:
        }
      }
    },
-   "failOnValidationErrors": false
+   "failOnValidationErrors": true
 }
 
 ```
-It' `failOnValidationErrors` property  determines if workflow execution should continue in case of validation
-errors. The default value of `failOnValidationErrors` is `true`.
-If `dataInputSchema` has the string type, it has the following definition:
 
-```json
-"dataInputSchema": "URL_to_json_schema"
-```
+If using string type, then the string value is the external schema URI and `failOnValidationErrors` default value of `true` is assumed.
 
-In this case the `failOnValidationErrors` default value of `true` is assumed.
+Example using string type
 
-The `dataInputSchema` property validates the [workflow data input](#Workflow-Data-Input). In case of
-a starting [Event state](#Event-state), it is not used to validate its event payloads.
+```json
+"dataInputSchema": "URI_to_json_schema"
+```
 
 The `secrets` property allows you to use sensitive information such as passwords, OAuth tokens, ssh keys, etc. inside your
 Workflow expressions.