Input and Output schema definition for SonataFlow

Input schema

The dataInputSchema in the Serverless Workflow specification is a parameter used in the workflow definition. The dataInputSchema parameter validates the workflow data input against a defined JSON Schema. It is important to provide dataInputSchema, as it is used to verify if the provided workflow data input is correct before any workflow states are executed.

You can define a dataInputSchema as follows:

dataInputSchema definition

"dataInputSchema": {
   "schema": "URL_to_json_schema",
   "failOnValidationErrors": false
}

In the previous definition, the schema property is a URI, which holds the path to the JSON schema used to validate the workflow data input. The URI can be a classpath URI, a file, or an HTTP URL. If a classpath URI is specified, then the JSON schema file must be placed in the resources section of the project or any other directory included in the classpath.

failOnValidationErrors is an optional flag that indicates the behavior adopted when the input data does not match the specified JSON schema. If not specified or set to true, an exception will be thrown and flow execution will fail. If set to false, the flow will be executed and a log of level WARN with the validation errors will be printed.

Output schema

Serverless Workflow specification does not support JSON output schema until version 0.9. Therefore, SonataFlow is implementing it as a Serverless Workflow specification extension. Output schema is applied after workflow execution to verify that the output model has the expected format. It is also useful for Swagger generation purposes.

Similar to Input schema, you must specify the URL to the JSON schema, using outputSchema as follows:

outputSchema definition

"extensions" : [ {
      "extensionid": "workflow-output-schema",
      "outputSchema": {
         "schema" : "URL_to_json_schema",
          "failOnValidationErrors": false
     }
  } ]

The same rules described for dataInputSchema apply for schema and failOnValidationErrors. The difference is that the latter flag is applied after workflow execution.

Example with `dataInputSchema` and `outputSchema`

You can see the serverless-workflow-expression-quarkus example application of a workflow definition with dataInputSchema and outputSchema.

Swagger documentation

When a workflow definition contains a dataInputSchema and/or outputSchema attribute, the workflow application generates an OpenAPI file, such as http://localhost:8080/q/openapi. The generated OpenAPI file references the schema file, which helps in defining the input and checking the output data for the workflows. For more information about the OpenAPI file, see OpenAPI specification.

If you want to generate an OpenAPI file for a workflow, then you must add the Quarkus dependency in the project.

Example component section with schema in an OpenAPI file

components:
  schemas:
    GeneralError:
      type: object
      properties:
        code:
          format: int32
          type: integer
        message:
          type: string

Additional resources

Found an issue?

If you find an issue or any misleading information, please feel free to report it here. We really appreciate it!