How to Create an Input Schema

A flow may require custom input when it is started. For example, it may require an email address, or a name to give to a new Globus guest collection, or some other input.

Flow authors can improve their users' experience by creating an input schema for the flow. The input schema can validate the input document that users submit when starting a flow.

Input schemas serve two purposes:

  1. Before starting a flow, the Globus Flows service uses the input schema to verify that the user input meets the flow’s input requirements.

  2. When starting the flow using the Globus Web App, the Web App uses the input schema to generate a graphical user interface that streamlines user input to the flow.

This overview will show you how to create an effective input schema for use with your flows.

1. A first look at input schemas

The Globus Flows service recognizes input schemas written in the JSON schema format. Here’s an example:

{
  "type": "object",
  "required": [
    "email_address"
  ],
  "properties": {
    "email_address": {
      "type": "string",
      "format": "email",
      "title": "Email address",
      "description": "A welcome email will be sent to this address."
    }
  },
  "additionalProperties": false
}

The input schema above ensures that when the associated flow is started, an input document must be provided that meets the following requirements:

  1. The input document is a JSON object.

  2. An "email_address" property must be specified.

  3. The "email_address" value must be a string that is formatted like an email address.

  4. The input document must have no other properties.

For example, the following input document would meet the schema requirements:

Valid input document
{
  "email_address": "user@example.com"
}

The following input documents would violate the schema requirements for various reasons:

Schema violation: The input document must be a JSON object
["This", "is", "an", "array"]
Schema violation: The "email_address" property must be present
{}
Schema violation: The "email_address" value must be a string
{
  "email_address": 42
}
Schema violation: No additional properties (e.g. "movie_quote") are allowed
{
  "email_address": "user@example.com",
  "movie_quote": "There is no spoon."
}

The Globus Flows service can catch many types of errors in input documents by validating the user’s input document against the flow’s input schema.

In addition, input schemas can help users start a flow using the Globus Web App, which can create a guided input GUI using the flow’s input schema.

2. The Globus Web App’s guided input form

Using the example input schema above, the Globus Web App will generate a guided input form for starting new flow runs that looks similar to this:

The Globus Web App's rendering of a required email address input field.

Notice that the Globus Web App has rendered the "title" and "description" properties in the input schema to inform the user what value should be entered. The input field has also been marked as required.

The input schema requires that the value of "email_address" is a string, but it also specifies that the string must match an email address format. The Globus Web App will ensure that the user input matches the formatting. If it doesn’t, the user will be notified of the error.

The email address input field is highlighted with an error message that states the value 42 does not match a known email format.

Input schemas can significantly improve the user experience when starting a flow. Let’s look at some other input field types, and introduce constraints that can help ensure user input is within expected ranges.

3. The "string" type

"string" is a common property type in input schemas. It supports multiple "format" constraints, including "email", which was seen above:

  • "email" (example: user@domain.com)

  • "uuid" (example: 60ac57ef-b078-4ae5-80dc-b3b2896b3bfc)

  • "date" (example: 2023-07-10)

Input schema
{
  "properties": {
    "start_date": {
      "type": "string",
      "format": "date",
      "title": "Start of date range",
      "description": "Entries older than this date will not be included."
    }
  }
}
An input field showing an error caused by user input that violates the date format constraint.
Figure 1. How the Globus Web App shows a date format constraint violation
A valid input document when starting a flow
{
  "start_date": "2023-07-10"
}

In addition to the formatting restriction above, it’s possible to specify other constraints:

  • minLength - the minimum length of the string

  • maxLength - the maximum length of the string

  • pattern - a regular expression that the string must match

Input schema
{
  "properties": {
    "codename": {
      "type": "string",
      "title": "Experiment codename",
      "description": "The codename registered for the experiment.",
      "minLength": 4,
      "maxLength": 20
    }
  }
}
An input field showing an error caused by user input that violates the minimum length constraint.
Figure 2. How the Globus Web App shows a length constraint violation
A valid input document when starting a flow
{
  "codename": "Cinderella"
}
Input schema
{
  "properties": {
    "beamline": {
      "type": "string",
      "title": "Beamline",
      "description": "The beamline used for the experiment.",
      "pattern": "^[1-9][0-9]?-(BM|ID)-[A-G]$"
    }
  }
}
An input field showing an error caused by user input that violates the pattern constraint.
Figure 3. How the Globus Web App renders a pattern constraint violation
A valid input document when starting a flow
{
  "beamline": "10-BM-A"
}

4. The "integer" type

"integer" is one of the numeric types supported by input schemas.

This type supports several constraints:

  • "exclusiveMinimum" (The user input must be greater than the exclusive minimum)

  • "minimum" (The user input must be greater than or equal to the minimum)

  • "exclusiveMaximum" (The user input must be less than the exclusive maximum)

  • "maximum" (The user input must be less than or equal to the maximum)

  • "multipleOf" (The user input must be a multiple of the multiple)

Input schema
{
  "properties": {
    "target_certainty": {
      "type": "integer",
      "title": "Target certainty",
      "description": "The certainty value desired for the calculation",
      "minimum": 95,
      "exclusiveMaximum": 100
    }
  }
}
An input field showing an error caused by user input that violates the range constraint.
Figure 4. How the Globus Web App renders a range constraint violation
A valid input document when starting a flow
{
  "target_certainty": 97
}

5. The "object" type

The input schemas above have validated flat input documents, where each key has a string or integer value. However, it’s also possible (and is often helpful) to group related properties together.

Here is a comparison of a flat input document and a nested input document:

Flat input document Nested input document 
{
  "initial_vector_angle": 137,
  "initial_vector_velocity": 57
}
 
{
  "initial_vector": {
    "angle": 137,
    "velocity": 57
  }
}

Validating the nested input document requires a new type: "object". This type was seen in the very first example schema at the top of the page; in that context it mandated that the entire input document must be a JSON object. Now it will be used to mandate that the "initial_vector" must also be a JSON object.

Flat input schema Nested input schema 
{
  "type": "object",
  "required": [
    "initial_vector_angle",
    "initial_vector_velocity"
  ],
  "properties": {
    "initial_vector_angle": {
      "type": "integer",
      "title": "Storm angle"
    },
    "initial_vector_velocity": {
      "type": "integer",
      "title": "Storm velocity"
    }
  }
}
 
{
  "type": "object",
  "required": [
    "initial_vector"
  ],
  "properties": {
    "initial_vector": {
      "type": "object",
      "required": [
        "angle",
        "velocity"
      ],
      "properties": {
        "angle": {
          "type": "integer",
          "title": "Storm angle"
        },
        "velocity": {
          "type": "integer",
          "title": "Storm velocity"
        }
      }
    }
  }
}

If you compare this nested input schema to the flat input schema, you will notice that the flat input schema is copied almost verbatim as the value of the "initial_vector" key. The property names have changed (e.g. "initial_vector_angle" is now simply "angle"), but the structure is identical.

5.1. Constraints

The "object" type can be constrained in multiple ways.

5.1.1. Requiring known properties

By default, input schemas allow input documents to have any properties and values. You can use the "required" property to list properties that must be present in the input document.

Table 1. An input schema with no required properties
Input schema Examples of valid input documents 
{
  "type": "object",
  "required": []
}
 

  1. {}

  2. {
  "velocity": "Ridiculously fast!"
}

  3. {
  "velocity": 88,
  "movie_quote": "Heavy!"
}

You can — and should — mandate that specific properties are submitted by using the "required" property and providing an array of values.

Table 2. An input schema that requires a "velocity" property
Input schema Examples of valid input documents 
{
  "type": "object",
  "required": [
    "velocity"
  ]
}

  1. No longer valid

  2. {
  "velocity": "Ridiculously fast!"
}

  3. {
  "velocity": 37,
  "movie_quote": "There is no spoon."
}

5.1.2. Excluding unknown properties

Just as it’s important to required specific properties, it is often important to exclude unknown properties. This is accomplished with the "additionalProperties" flag, which defaults to true.

Table 3. An input schema that allows unknown properties
Input schema Examples of valid input documents 
{
  "type": "object",
  "properties": {
    "velocity": {
      "type": "integer"
    }
  },
  "additionalProperties": true
}
 

  1. {}

  2. {
  "velocity": 88
}

  3. {
  "velocity": 88,
  "movie_quote": "Great Scott!"
}

It is common practice to exclude unknown properties by setting "additionalProperties" to false:

Table 4. An input schema that rejects unknown properties
Input schema Examples of valid input documents 
{
  "type": "object",
  "properties": {
    "velocity": {
      "type": "integer"
    }
  },
  "additionalProperties": false
}

  1. Remember that the input schema does not require any properties.

    {}

  2. {
  "velocity": 88
}

  3. No longer valid

6. Constant or default values

Sometimes it is helpful to provide a constant or default value for an input field. Using the "default" keyword provides an initial but changeable value for the field while "const" provides a fixed value that cannot be changed and will produce an error if a different value is submitted by the user.

The Globus Web App recognizes a "default" property for input fields, and will use that value as the default value for the input field in the guided input form but still allow the value to be changed. The "const" property will be used as the default value and will not allow the value to be changed.

An input schema demonstrating how to use the "default" keyword
{
  "properties": {
    "some_id": {
      "type": "string",
      "default": "1111-2222-3333-4444-5555"
    }
  }
}
An input schema demonstrating how to use the "const" keyword
{
  "properties": {
    "important_number": {
      "type": "number",
      "const": 3.14
    }
  }
}

Both "default" and "const" can also be used with all of the Globus formats as well.

An example using "const" with "globus-collection" format
{
  "type": "object",
  "required": [
    "source"
  ],
  "properties": {
    "source": {
      "type": "object",
      "format": "globus-collection",
      "title": "Source collection and path",
      "required": [
        "id",
        "path"
      ],
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "path": {
          "type": "string"
        }
      },
      "const": {
        "id": "ec160529-be4e-47bf-8c46-899e96e14909",
        "path": "/"
      }
      "additionalProperties": false
    }
  }
}
An example using "const" with "globus-principal" format
{
  "type": "object",
  "format": "globus-principal",
  "const": {
    "id": "1d611a6d-9a22-4de5-b855-ba793df9b309",
    "urn": "urn:globus:auth:identity:1d621a6d-9a22-4de5-b855-ba793df4b309",
    "type": "identity"
  }
}

7. Providing hints to the guided input form

The Globus Web App uses input schemas to generate a guided input form. As seen previously, flow authors can use the "title" and "description" properties to improve that user interface for users. There are other ways that flow authors can improve the interface.

7.1. The "globus-collection" format

When writing a flow that interacts with the Globus Transfer service, it is common to accept a Globus collection and/or a path as inputs to the flow. The Globus Web App recognizes a unique "object" format, "globus-collection", which it uses to generate a user interface that supports searching for Globus collections and browsing for paths on a selected collection.

An input schema using "globus-collection" 
{
  "type": "object",
  "required": [
    "source"
  ],
  "properties": {
    "source": {
      "type": "object",
      "format": "globus-collection",
      "title": "Source collection and path",
      "required": [
        "id",
        "path"
      ],
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "path": {
          "type": "string"
        }
      },
      "additionalProperties": false
    }
  }
}
A screenshot showing that the Globus Web App renders a 'globus-collection'-formatted object in a custom, user-friendly format
Figure 5. How the Globus Web App renders a "globus-collection"-formatted object

The Globus Web App only recognizes the "globus-collection" format for "object" types, and the nested properties must be named "id" and "path". One or both of the "id" and "path" properties must be included.

An example of the input document the Globus Web App will submit to the Flows service
{
  "source": {
    "id": "ec160529-be4e-47bf-8c46-899e96e14909",
    "path": "/~/"
  }
}

7.2. The "globus-principal" format

Many flows will require information about a particular identity or group in order to accomplish their tasks. For example, a flow that wishes to grant a user access to a particular collection will need that user’s identity ID. The Globus Web App recognizes a unique "object" or "array" type combined with a format value of "globus-principal". This format will generate a particular user interface so that searching for and selecting these principal values as part of the input to a flow is much easier.

Example selecting a single principal value

An input schema using "globus-principal" to select a single principal using the "object" type
{
  "title": "Select a Globus Identity or Group",
  "type": "object",
  "required": [
    "principal"
  ],
  "properties": {
    "principal": {
      "type": "object",
      "title": "Principal",
      "format": "globus-principal"
    }
  },
  "additionalProperties": false
}
An example of the input document the Globus Web App will submit to the Flows service using the "object" type
{
  "principal": {
    "id": "11111111-7f6d-11e9-9cda-0a06afd4a22e",
    "type": "identity",
    "urn": "urn:globus:auth:identity:e7c0c8e4-7f6d-11e9-9cda-0a06afd4a22e"
  }
}

Example selecting multiple principal values

An input schema using "globus-principal" to select multiple principals using the "array" type
{
  "title": "Select Globus Identities and Groups",
  "type": "object",
  "required": [
    "principals"
  ],
  "properties": {
    "principals": {
      "type": "array",
      "title": "Principals",
      "format": "globus-principal"
    }
  },
  "additionalProperties": false
}
An example of the input document the Globus Web App will submit to the Flows service using the "array" type
{
  "principals": [
    {
      "id": "11111111-7f6d-11e9-9cda-0a06afd4a22e",
      "urn": "urn:globus:auth:identity:11111111-9a22-4de5-b855-ba793df9b309",
      "type": "identity"
    },
    {
      "id": "22222222-7f6d-11e9-9cda-0a06afd4a22e",
      "urn": "urn:globus:groups:id:22222222-7f6d-11e9-9cda-0a06afd4a22e",
      "type": "group"
    }
  ]
}
A screenshot showing that the Globus Web App renders a 'globus-principal'-formatted field in a custom, user-friendly format
Figure 6. How the Globus Web App renders a "globus-principal"-format

7.3. The "globus-transfer-transfer#0.10" format

At this time, we only recommend using this format for flows that are associated with collections (via associated_flow_policy).

To simplify the ability to provide a DATA_TYPE: "transfer" object (see Transfer Documentation) as input flow authors can specify a format value of "globus-transfer-transfer#0.10".

This format is especially useful for flows that are associated with collection transfer actions.

Example

An input schema using "globus-transfer-transfer#0.10" 
{
  "title": "Start a Transfer",
  "type": "object",
  "required": [
    "file_manager_settings"
  ],
  "properties": {
    "file_manager_settings": {
      "type": "object",
      "format": "globus-transfer-transfer#0.10"
    }
  },
  "additionalProperties": false
}

How the Globus Web App renders a "globus-transfer-transfer#0.10"-format

The Globus Web App’s Guided Start implementation of the "globus-transfer-transfer#0.10" format is designed to be used with flows that are associated with collection transfer actions, where the user has started their transfer intent in the File Manager.

When an associated flow policy is detected on a collection and the user is redirected from the File Manager to the Guided Start page, the Web App will display the collections the user selected in the File Manager, number of items selected, and all of the options the user selected in the File Manager as JSON.

Figure 7. When redirected from the File Manager

When a user attempts to access the Guided Start page of a flow that references the format directly, the Web App will display a message indicating that the user should start their configuration process in the File Manager.

Figure 8. When the user accesses the flow directly

7.4. Ordering input fields in the guided input form

Sometimes it’s helpful to order the input fields in the guided input form. For example, it is common for a "source" field to appear before a "destination" field. The Globus Web App recognizes a "propertyOrder" property for "object" types, which allows flow authors to make the guided input form more intuitive for users. The "propertyOrder" is a list of properties in the order they should appear in the guided input form.

An input schema demonstrating how to use "propertyOrder" 
{
  "type": "object",
  "propertyOrder": [
    "3",
    "2",
    "1"
  ],
  "properties": {
    "1": {
      "type": "string"
    },
    "2": {
      "type": "string"
    },
    "3": {
      "type": "string"
    }
  }
}

8. Advanced Topic: The Flows Metaschema

JSON Schemas can, themselves, be validated under meta-schemas, the schemas which describe other schemas.

Globus Flows accepts a variant of the commonly used Draft 7 JSON Schema meta-schema, but it is customized in a number of ways in order to encode the fact that Globus Flows does not support all JSON Schema features.

Input schemas can be validated under the following schema.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://docs.globus.org/api/flows/jsonschema-strict-1.0.json",
  "title": "Globus Flows meta-schema",
  "type": "object",
  "properties": {
    "$id": {
      "type": "string",
      "format": "uri-reference"
    },
    "$schema": {
      "enum": [
        "https://docs.globus.org/api/flows/jsonschema-strict-1.0.json",
        "http://json-schema.org/draft-07/schema#"
      ]
    },
    "$comment": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "examples": {
      "type": "array",
      "items": true
    },
    "type": {
      "enum": [
        "object"
      ]
    },
    "properties": {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/definitions/propertyDefinition"
      }
    },
    "required": {
      "$ref": "#/definitions/stringArray"
    },
    "additionalProperties": {
      "type": "boolean"
    },
    "propertyOrder": {
      "$ref": "#/definitions/stringArray"
    }
  },
  "additionalProperties": false,
  "definitions": {
    "propertyDefinition": {
      "oneOf": [
        {
          "$ref": "#/definitions/booleanPropertyDefinition"
        },
        {
          "$ref": "#/definitions/numericPropertyDefinition"
        },
        {
          "$ref": "#/definitions/stringPropertyDefinition"
        },
        {
          "$ref": "#/definitions/objectPropertyDefinition"
        },
        {
          "$ref": "#/definitions/arrayPropertyDefinition"
        },
        {
          "$ref": "#/definitions/enumPropertyDefinition"
        },
        {
          "$ref": "#/definitions/constPropertyDefinition"
        }
      ]
    },
    "booleanPropertyDefinition": {
      "type": "object",
      "properties": {
        "$comment": {
          "type": "string"
        },
        "title": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "default": true,
        "type": {
          "enum": [
            "boolean"
          ]
        }
      },
      "additionalProperties": false,
      "required": [
        "type"
      ]
    },
    "numericPropertyDefinition": {
      "type": "object",
      "properties": {
        "$comment": {
          "type": "string"
        },
        "title": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "default": true,
        "type": {
          "enum": [
            "integer",
            "number"
          ]
        },
        "multipleOf": {
          "type": "number",
          "exclusiveMinimum": 0
        },
        "maximum": {
          "type": "number"
        },
        "exclusiveMaximum": {
          "type": "number"
        },
        "minimum": {
          "type": "number"
        },
        "exclusiveMinimum": {
          "type": "number"
        }
      },
      "additionalProperties": false,
      "required": [
        "type"
      ]
    },
    "stringPropertyDefinition": {
      "type": "object",
      "properties": {
        "$comment": {
          "type": "string"
        },
        "title": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "default": true,
        "type": {
          "enum": [
            "string"
          ]
        },
        "enum": {
          "$ref": "#/definitions/stringArray"
        },
        "format": {
          "type": "string"
        },
        "pattern": {
          "type": "string",
          "format": "regex"
        },
        "maxLength": {
          "$ref": "#/definitions/nonNegativeInteger"
        },
        "minLength": {
          "$ref": "#/definitions/nonNegativeIntegerDefault0"
        }
      },
      "additionalProperties": false,
      "required": [
        "type"
      ]
    },
    "objectPropertyDefinition": {
      "type": "object",
      "properties": {
        "$comment": {
          "type": "string"
        },
        "title": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "default": true,
        "type": {
          "enum": [
            "object"
          ]
        },
        "format": {
          "type": "string"
        },
        "properties": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/definitions/propertyDefinition"
          }
        },
        "required": {
          "$ref": "#/definitions/stringArray"
        },
        "additionalProperties": {
          "type": "boolean"
        },
        "propertyOrder": {
          "$ref": "#/definitions/stringArray"
        }
      },
      "additionalProperties": false,
      "required": [
        "type"
      ]
    },
    "arrayPropertyDefinition": {
      "type": "object",
      "properties": {
        "$comment": {
          "type": "string"
        },
        "title": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "default": true,
        "type": {
          "enum": [
            "array"
          ]
        },
        "format": {
          "type": "string"
        },
        "items": {
          "oneOf": [
            {
              "$ref": "#/definitions/propertyDefinition"
            },
            {
              "type": "array",
              "items": {
                "$ref": "#/definitions/propertyDefinition"
              }
            }
          ]
        },
        "maxItems": {
          "$ref": "#/definitions/nonNegativeInteger"
        },
        "minItems": {
          "$ref": "#/definitions/nonNegativeIntegerDefault0"
        }
      },
      "additionalProperties": false,
      "required": [
        "type"
      ]
    },
    "enumPropertyDefinition": {
      "type": "object",
      "properties": {
        "$comment": {
          "type": "string"
        },
        "title": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "default": true,
        "enum": {
          "type": "array",
          "items": true,
          "minItems": 1,
          "uniqueItems": true
        }
      },
      "additionalProperties": false,
      "required": [
        "enum"
      ]
    },
    "constPropertyDefinition": {
      "type": "object",
      "properties": {
        "$comment": {
          "type": "string"
        },
        "title": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "type": {
          "enum": [
            "array",
            "boolean",
            "integer",
            "null",
            "number",
            "object",
            "string"
          ]
        },
        "const": true
      },
      "additionalProperties": false,
      "required": [
        "const"
      ]
    },
    "nonNegativeInteger": {
      "type": "integer",
      "minimum": 0
    },
    "nonNegativeIntegerDefault0": {
      "allOf": [
        {
          "$ref": "#/definitions/nonNegativeInteger"
        },
        {
          "default": 0
        }
      ]
    },
    "stringArray": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "uniqueItems": true,
      "default": []
    }
  }
}

9. Next steps

Please see our How to Run a Flow guide for a description of how to run your flow using the Globus Web App.