Validating Flow Definitions

Flow authors can improve their development process by validating flow definitions before using them in a flow. Validation of flow definitions is available with the Globus CLI or the Flows IDE.

Using the Globus CLI

Using the command below, you may validate a flow definition that is stored in a file named DEFINITION.json and an input schema that is stored in a file named INPUT_SCHEMA.json. The usage of --input-schema is not required but is recommended for more advanced validation. For a complete list of command options, see the globus flows validate Reference.

$ globus flows validate DEFINITION.json --input-schema INPUT_SCHEMA.json

The CLI will return a message indicating whether or not the flow definition passes validation. If the flow definition passes validation, the CLI will return a message that resembles the following:

Analysis
========
Possible State Traversals: 1

Discovered Scopes
=================
RunAs | Scope
----- | -------------------------------------------------------------
User  | https://auth.globus.org/scopes/actions.globus.org/hello_world

If the flow definition does not pass validation, the CLI will return an error message that resembles the following:

HTTP status:      422
code:             UNPROCESSABLE_ENTITY
message:          2 validation errors
errors:
                  $.definition.StartAt: field required
                  $.definition.States: field required

See Troubleshooting Validation Errors below for more information on the types of problems validation can detect.

Using the Flows IDE

Important
At the time of writing, the Flows IDE is in beta. The interface may change with future versions. The validation of input schemas is not currently supported.

The Flows IDE contains two panes: the pane on the left contains a text editor for flow definitions, while the right side displays an interactive diagram view. As a flow definition is updated in the editor, the diagram view updates in real time to reflect the changes.

A flow definition can be written directly in the IDE, or pasted in from another source. See Write A Flow Definition for examples that can be used in the editor.

If a user is not logged in, the editor will be in non-authenticated mode. In non-authenticated mode, the Flows IDE will provide limited functionality, such as live editing, syntax error highlighting (wavy underlines), and diagram visualization. The syntax error highlighting will display on parts of the flow definition in the editor. In most cases, alert messages will also be displayed in the diagram view. If the flow definition contains errors, the diagram view will be disabled until all the errors are corrected.

To access more advanced validation, authentication is required. The "Sign In" button is located at the top right of the page. After logging in, the "Validate" button at the bottom of the editor will be enabled. Click the "Validate" button to run a series of advanced checks on the flow definition.

See Troubleshooting Validation Errors below for more information on the types of problems that can be detected by the validation process.

Troubleshooting Validation Errors

Common Errors

The common errors found by validation are focused on the structure of the flows definition. For example, validating required top-level fields, required state-specific fields, data types, valid JSON objects/paths, and more. Validation errors are designed to provide detailed error messages to help users locate problems in their flow definitions. Below are some examples of common errors that validation can catch:

$.definition.<Field>: field required

If validation determines that a field is missing from the flow definition, the error message will indicate that it is required. To fix this problem, ensure these fields are present in the flow definition. See Authoring Flows Introduction for more information.

$.definition.States.<State>: Discriminator '<Field>' is missing in value

If validation determines that any required fields are missing from a state in a flow definition, the error message will list all the missing fields. To fix this problem, ensure that the required fields are present for that state in the definition.

$.definition.States.<State>: A state of type 'Action' must be defined as either terminal ("End": true) or transitional ("Next": "<NextStateId>")

If validation determines that a state of type Action is not defined as either terminal or transitional, the error message will indicate where in the flow definition the problem is located. To fix this problem, ensure that the state contains either "End": true or "Next": "<NextStateId>". See Actions page for more information.

$.definition.States.<State>.Parameters.<Param>: Must be a valid JSONPath

Validation raises this error when a provided path is not valid JSONPath. Deeply-nested parameters will refer to their array indices and object keys (e.g., Parameters.a[0].b[0][1]['endpoint_id']). To fix this problem, locate the invalid parameter and correct the JSONPath expression.

$.definition.States.<State>.<Field>: extra fields not permitted

Validation raises this error when a provided key is not permitted. To fix this problem, find the problematic field and remove it from the flow definition.

Logic and Other Errors

This flow contains legacy action providers in the action state(s): [<State1>, <State2>, …​]

If validation determines that a flow contains legacy action providers, the error message will indicate where in the flow definition the problem is located. To fix this problem, migrate the flow definition from legacy action providers. See Hosted Action Providers and Migration Guide to migrate from legacy action providers.

Analysis of the Flow definition required traversal of too many possibilities.

If validation detects a high number of possible paths within the flow definition the process will halt and return this error. The flow definition may be correct, but the validation cannot continue to process the flow definition accurately.

An attempt was made to read data improperly during analysis. A known constraint was violated in state <State>: Attempted to access key …​

If validation determines that the state definition is attempting to access a key that it cannot retrieve it will provide an error message with details about the invalid and valid keys. For example, the input schema defines a mandatory key named apples but the flow definition contains a typo like $.apple. To fix this problem, review the error message and ensure that the state definition is accessing a valid key.

Failed to resolve scope for Action Provider at '<ActionUrl>': <ErrorMessage>

If validation is unable to resolve the scope for an action provider, an error message will be provided with details about the error. To fix this problem, review the error message and ensure that the action provider is reachable, provides the correct scope, or returns valid JSON.

Errors Validation Cannot Catch

While flows validation is extensive and extremely valuable for identifying problems in a flow definition, there are some problems that it is not able to catch.

Invalid Expressions

Expressions evaluate multiple parts of a state to compute a value. See Expressions for more information. Validation cannot determine if the expression written is correct due to the values being created dynamically as the flow runs. It is recommended that users test their expressions in a flow to ensure they are evaluated as expected.

Dynamic Changes to Data as a Flow Runs

There are limitations to what flows validation can catch as it does analysis on a flow definition. If a flow uses expression evaluation to transform data as it runs the validation will not be able to catch these changes.

Infinite Loops

Validation is not able to detect infinite loops in a flow definition. An infinite loop for a flow definition is when a flow state transitions to itself or another state that transitions back to the original state in a cycle indefinitely. It is recommended users test their flows to ensure they do not contain infinite loops.