Validate a task | ArcGIS REST APIs

URL:: https://<task-url>/validate
Methods:: GETPOST
Version Introduced:: 12.0

Description

The validate operation allows users to optionally validate their input before running the submitJob or execute operations. The validate operation can also return when parameter inputs have been updated, such as when a filter has been updated, or when a parameter has been enabled or disabled. It can also provide system or custom validation messages. This operation is only available when the validate capability is enabled for a geoprocessing service. To learn more about about publishing a geoprocessing service with the validation capability, see web tool and geoprocessing service settings.

The validate operation only supports synchronous requests. Clients submitting a validate request must wait to get a response. It shares the same system resources with those handling the query of job status, responding to task queries, receiving inputs from clients and sending outputs back to clients. Limit the number of validate requests or increase the number of instances to avoid impacting the performance of other queries and operations. The tool author also needs to consider writing efficient validation code to ensure the validate operation performance.

Request parameters

The request parameters are similar to those of the Execute operation, except for how you provide values for individual parameters of your geoprocessing task. Many of the options listed below may not be needed in most requests. None of the options are required; even if you have a required input parameter, you can skip it and the default value will be used. You will also see options to provide values for the output parameter. This option is only needed when you want to specify any of the tags listed in the syntax. The value itself will be ignored because output values do not apply if the tool has not yet run.

Parameter Details

Parameter	Details
`<gpParameter1>, <gpParameter2>, ...` (Optional)	The valid values for the parameters are optional validation tags, along with an optional value which is dependent on the data type of the parameter. These parameters are in the `parameters` array of the JSON representation associated with the Task resource.
`context` (Optional)	The `context` parameter supports `outSR`, `processSR`, and `extent`: `outSR` is the spatial reference of the output geometries. `processSR` is the spatial reference that the model will use to perform geometry operations. Note The spatial reference can be specified as either a well-known ID or as a spatial reference JSON object. If `outSR` is not specified, the output geometries will be in the spatial reference of the input geometries. If `processSR` is specified and `outSR` is not specified, the output geometries will be in the spatial reference of the process spatial reference. `extent` will only process features that overlap the specified extent. The output features will have an extent that is the same or larger than the `extent` value. The syntax for `extent` follows the syntax of the `envelope` object.
`returnZ` (Optional)	If `true`, the 'hasZ' property of the validate result will be also `true` if your input has Z values. Values: `true` \| `false`
`returnM` (Optional)	If `true`, the 'hasM' property of the validate result will be also `true` if your input has M values. Values: `true` \| `false`
`returnFeatureCollection` (Optional)	If `true`, the result will be returned as a feature collection including fields, geometry type and other applicable information in the `layerDefinition` property. The `features` in the `featureSet` property will always be an empty array as features are not returned in the validate operation. The default is `false`. Values: `true` \| `false`
`returnColumnName` (Optional)	If `true`, column names of all columns of the `GPValueTable` result will be returned when all columns have a unique and not empty name. The default is `false`. Values: `true` \| `false`
`simplifyFeatures` (Optional)	There is an option to maintain the original input geometry without simplifying it by setting this option to `false`. Setting it to `true` will simplify the geometry of the input features, but it may significantly slow the validate operation. The default value is `false`. Values: `true` \| `false`
`updateValues` (Optional)	This option controls whether the validation code will change any of the values of any parameters. When set to `false`, you will not see any values for any parameters in the response. The default value is `true`. Values: `true` \| `false`
`discreteValidateMsgs` (Optional)	When there are multiple validation messages for individual columns in a `GPValueTable` parameter, this option determines the format of those messages for individual columns in `GPValueTable` or `GPComposite` parameters. When set to `true`, the messages will be in a list of lists format, with possible `null` placeholders for columns or composites that do not have a message. When set to `false`, all messages will be combined into a single message, and the most severe message level among them will become the message level of the combined message. The default value is `false`. Values: `true` \| `false`
`f` (Optional)	The response format. The default response format is `html`. Values: `html` \| `json` \| `geojson` \| `pjson`

<gpParameter1>, <gpParameter2>, ...

(Optional)

The valid values for the parameters are optional validation tags, along with an optional value which is dependent on the data type of the parameter. These parameters are in the parameters array of the JSON representation associated with the Task resource.

context

(Optional)

The context parameter supports outSR, processSR, and extent:

outSR is the spatial reference of the output geometries.
processSR is the spatial reference that the model will use to perform geometry operations.

Note
The spatial reference can be specified as either a well-known ID or as a spatial reference JSON object. If outSR is not specified, the output geometries will be in the spatial reference of the input geometries. If processSR is specified and outSR is not specified, the output geometries will be in the spatial reference of the process spatial reference.
extent will only process features that overlap the specified extent. The output features will have an extent that is the same or larger than the extent value. The syntax for extent follows the syntax of the envelope object.

returnZ

(Optional)

If true, the 'hasZ' property of the validate result will be also true if your input has Z values.

Values: true | false

returnM

(Optional)

If true, the 'hasM' property of the validate result will be also true if your input has M values.

Values: true | false

returnFeatureCollection

(Optional)

If true, the result will be returned as a feature collection including fields, geometry type and other applicable information in the layerDefinition property. The features in the featureSet property will always be an empty array as features are not returned in the validate operation. The default is false.

Values: true | false

returnColumnName

(Optional)

If true, column names of all columns of the GPValueTable result will be returned when all columns have a unique and not empty name. The default is false.

Values: true | false

simplifyFeatures

(Optional)

There is an option to maintain the original input geometry without simplifying it by setting this option to false. Setting it to true will simplify the geometry of the input features, but it may significantly slow the validate operation. The default value is false.

Values: true | false

updateValues

(Optional)

This option controls whether the validation code will change any of the values of any parameters. When set to false, you will not see any values for any parameters in the response. The default value is true.

Values: true | false

discreteValidateMsgs

(Optional)

When there are multiple validation messages for individual columns in a GPValueTable parameter, this option determines the format of those messages for individual columns in GPValueTable or GPComposite parameters.

When set to true, the messages will be in a list of lists format, with possible null placeholders for columns or composites that do not have a message.

When set to false, all messages will be combined into a single message, and the most severe message level among them will become the message level of the combined message. The default value is false.

Values: true | false

f

(Optional)

The response format. The default response format is html.

Values: html | json | geojson | pjson

Request GP Parameter

For the first request parameter <gpParameter1>, <gpParameter2>, ... of the validate operation, special syntax or schema needs to be followed.

Request GP Parameter JSON Schema

Although the isAltered, isEnabled, hasBeenValidated and value tags are optional, providing accurate tags will provide expected validation behavior. The isAltered tag will have a default value of true if there is a value provided for that parameter. Otherwise, it will be false. The isEnabled tag will have a default value of true if not provided. The hasBeenValidated tag will have a default value of false if not provided.

In many cases, you can skip providing anything for output parameters, unless your validation will respond differently based on an output parameter.

Use dark colors for code blocksCopy
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Validate parameter schema",
  "type": "object",
  "properties": {
    "isAltered": {
      "type": "boolean",
      "description": "Indicates whether the parameter has been altered."
    },
    "isEnabled": {
      "type": "boolean",
      "description": "Indicates whether the parameter is enabled.",
      "default": true
    },
    "hasBeenValidated": {
      "type": "boolean",
      "description": "Indicates whether the parameter has been validated.",
      "default": false
    },
    "value": {
      "description": "The value of your input parameter, follow the syntax or JSON schema for that data type.",
    }
  },
  "additionalProperties": false
}

Request GP Parameter Examples

The following example shows the validation request declares there is a change in the value a user has provided for the inputString parameter, it has not been validated considering this is the first validate request.

Use dark colors for code blocksCopy
{
    "isAltered": true,
    "isEnabled": true,
    "hasBeenValidated": false,
    "value": "US West Regions"
}

This example shows providing a value for an input feature parameter. The hasBeenValidated tag is set to true because of previous validate request this user may have requested, and there is no further validation outcome is expected from this parameter. However, other parameters depending on this parameter may have various validation responses.

Use dark colors for code blocksCopy
{
    "isAltered": true,
    "isEnabled": true,
    "hasBeenValidated": true,
    "value": {"url":"URL to a hosted feature service layer"}
}

Validate Request Schema

The JSON schema for the full validate request.

Use dark colors for code blocksCopy
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "HTTP Request Parameters Schema",
  "type": "object",
  "properties": {
    "parameters": {
      "type": "array",
      "description": "Optional validation tags and values depending on the data type of the parameter. These parameters are in the 'parameters' array of the JSON representation associated with the 'task' resource.",
      "items": {
        "type": "object",
        "properties": {
          "isAltered": {
            "type": "boolean",
            "description": "Indicates whether the parameter has been altered.",
            "default": false
          },
          "isEnabled": {
            "type": "boolean",
            "description": "Indicates whether the parameter is enabled.",
            "default": true
          },
          "hasBeenValidated": {
            "type": "boolean",
            "description": "Indicates whether the parameter has been validated.",
            "default": false
          },
          "value": {
            "description": "The value of your input parameter, follow the syntax or JSON schema for that data type."
          }
        }
      }
    },
    "context": {
      "type": "object",
      "description": "Optional context settings for spatial reference and extent.",
      "properties": {
        "outSR": {
          "description": "Spatial reference of the output geometries. Can be a well-known ID or a spatial reference JSON object.",
          "oneOf": [
            { "type": "integer" },
            { "type": "object" }
          ]
        },
        "processSR": {
          "description": "Spatial reference used for geometry operations. Can be a well-known ID or a spatial reference JSON object.",
          "oneOf": [
            { "type": "integer" },
            { "type": "object" }
          ]
        },
        "extent": {
          "description": "Processes only features overlapping the specified extent. Follows the 'envelope' object syntax.",
          "type": "object"
        }
      },
      "additionalProperties": false,
    },
    "returnZ": {
      "type": "boolean",
      "description": "If true, the 'hasZ' property of the validate result will be true if input has Z values.",
      "default": false
    },
    "returnM": {
      "type": "boolean",
      "description": "If true, the 'hasM' property of the validate result will be true if input has M values.",
      "default": false
    },
    "returnFeatureCollection": {
      "type": "boolean",
      "description": "If true, returns the result as a feature collection.",
      "default": false
    },
    "returnColumnName": {
      "type": "boolean",
      "description": "If true, returns column names of all columns of the GPValueTable result when all columns have unique and non-empty names.",
      "default": false
    },
    "simplifyFeatures":{
      "type": "boolean",
      "description": "There is an option to maintain the original input geometry without simplifying it by setting this option to `false`.",
      "default": false
    },
    "updateValues": {
      "type": "boolean",
      "description": "This option controls whether the validation code will change any of the values of any parameters. When set to false, you will not see any values for any parameters in the response.",
      "default": true
    },
    "discreteValidateMsgs": {
      "type": "boolean",
      "description": "When there are multiple validation messages for individual columns for a GPValueTable parameter, this option determines the format of the validation messages for individual columns in the GPValueTable or GPComposite parameters.",
      "default": false
    },
    "f": {
      "type": "string",
      "description": "Response format.",
      "enum": ["html", "json", "geojson"],
      "default": "html"
    }
  },
  "additionalProperties": false
}

Validate response

The validate operation will respond with all validation messages, any changes of any parameters, including their enabled or disabled status, updated filters or choice list, isAltered and hasBeenValidated tags, for all input and output parameters. The additionalMessages field is seldom present, and only when validation returns extra messages in addition to those for each parameter.

The validation message will always have error, warning, and info levels. Regardless the showMessages value in the properties of your geoprocessing service configuration JSON, even if you set showMessages to NONE, all validation messages, regardless of their level, will still be available in the response.

The value of each parameter may or may not be available. The individual features for a GPFeatureRecordSetLayer or a GPRecordSet will never be available in the values in the response. However, you can always access the schema or the feature collection of it if needed. If your input is using an URL to a hosted feature layer for example, that URL will be still available in the response.

Similar to the value, filters and choice lists are only available in the response if they apply.

For output parameters, you can ignore them in many cases. You may see default values for them, which is based on the output when the tool publisher originally runs the tool before publishes it. You can always remove the default values for output parameters during the publishing process to ensure those results will not be accessible to the validate operation.

Based on the validation response, clients like a custom web application can adjust the user interface of each parameter of the geoprocessing service to reflect any changes.

Response JSON schema

Use dark colors for code blocksCopy
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "validationResults": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "the name of the parameter."
          },
          "isAltered": {
            "type": "boolean"
          },
          "hasBeenValidated": {
            "type": "boolean",
            "default": true
          },
          "isEnabled": {
            "type": "boolean"
          },
          "value": {
            "description": "The value of the parameter, follow the syntax or JSON schema for that data type."
          },
          "choiceList":{
            "type": "array",
            "description": "Updated choice list.",
            "items": {
                "type": "string"
            },
            "uniqueItems": true
          },
          "filter":{
            "type": "object",
            "description": "Updated filter. See the JSON schema for filter at GP Task page."
          },
          "message": {
            "oneOf": [
              {
                "type": "array",
                "items": {}
              },
              {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "integer"
                  },
                  "type": {
                    "type": "string",
                    "enum": ["error", "warning", "info"]
                  },
                  "description": {
                    "type": "string"
                  }
                },
                "required": ["code", "description", "type"]
              }
            ]
          }
        },
        "required": ["name", "isAltered", "hasBeenValidated", "isEnabled"]
      }
    },
    "additionalMessages": {
      "type": "array",
      "items": {}
    }
  },
  "required": ["validationResults"]
}

Validate Request and Response Examples

The following examples demonstrate a series of validate request from a user before they run the geoprocessing service. These examples assume the geoprocessing service has four input parameters and one output parameter. The sequence of requests are listed below:

Input_Features with a data type of GPFeatureRecordSetLayer. This is a required parameter.
Input_Field with a data type of Field and it depends on the previous Input_Features parameter. This is a required parameter. There is a field filter allowing only fields with a double data type.
Input_Number with a data type of GPLong. This is an optional parameter.
Input_Author with a data type of GPString. This is an optional parameter.
Output_Table with a data type of GPRecordSet. This is a derived output parameter.

First Request

In the first validate request, only the values of Input_Features is provided. Considering a new value is provided other than the default value, isAltered should be set to true. In the JSON payload below, only the first input parameter is set.

Use dark colors for code blocksCopy
{
    "Input_Features":{
        "isAltered": true,
        "hasBeenValidated": false,
        "isEnabled": true,
        "value": {
            "url": "https://machine.domain.com/webadaptor/rest/services/Hosted/InputFeatures/0"
        }
    }
}

First Response

The response will have the updated field list and domains for the Input_Field parameter. The value of the Input_Features was returned because it is an URL format. For all other parameters, because there is nothing specified in the request, default values were used.

Use dark colors for code blocksCopy
{
    "validationResults":[
        {
            "isAltered": true,
            "hasBeenValidated": true,
            "isEnabled": true,
            "name": "Input_Features",
            "value":{
                "url": "https://machine.domain.com/webadaptor/rest/services/Hosted/InputFeatures/0"
            }
        },
        {
            "isAltered": false,
            "hasBeenValidated": true,
            "isEnabled": true,
            "name": "Input_Field",
            "choiceList": ["area"],
            "filter": {
                "type": "codedValue",
                "list": [{
                    "dataType": "Field",
                    "name": "area",
                    "value": {
                    "nullable": true,
                    "editable": true,
                    "name": "area",
                    "length": 8,
                    "alias": "area",
                    "type": "esriFieldTypeDouble"
                    }
                }]
            }
        },
        {
            "isAltered": false,
            "hasBeenValidated": true,
            "isEnabled": true,
            "name": "Input_Number"
        },
        {
            "isAltered": false,
            "hasBeenValidated": true,
            "isEnabled": true,
            "name": "Input_Author"
        },
        {
            "isAltered": false,
            "hasBeenValidated": true,
            "isEnabled": true,
            "name": "Output_Table"
        }
    ]
}

Second Request

With the response above, a user can pick a field listed in the validate response. In this case, there is only one field having the double type, and the user chose that. However, there are still some validation logic will change the behavior after both the input feature and input fields are provided. So, a second validate request is sent as the following:

Use dark colors for code blocksCopy
{
    "Input_Features":{
        "isAltered": true,
        "hasBeenValidated": true,
        "isEnabled": true,
        "value": {
            "url": "https://machine.domain.com/webadaptor/rest/services/Hosted/InputFeatures/0"
        }
    },
    "Input_Field":{
        "isAltered": true,
        "hasBeenValidated": false,
        "isEnabled": true,
        "value": {
            "nullable": true,
            "editable": true,
            "name": "area",
            "length": 8,
            "alias": "area",
            "type": "esriFieldTypeDouble"
        }
    }
}

Second Response

With both the input features and and input field selected, validation code is further customizing the parameters with updated values for the Input_Number parameter.

Use dark colors for code blocksCopy
{
    "validationResults":[
        {
            "isAltered": true,
            "hasBeenValidated": true,
            "isEnabled": true,
            "name": "Input_Features",
            "value":{
                "url": "https://machine.domain.com/webadaptor/rest/services/Hosted/InputFeatures/0"
            }
        },
        {
            "isAltered": true,
            "hasBeenValidated": true,
            "isEnabled": true,
            "name": "Input_Field",
            "choiceList": ["area"],
            "filter": {
                "type": "codedValue",
                "list": [{
                    "dataType": "Field",
                    "name": "area",
                    "value": {
                    "nullable": true,
                    "editable": true,
                    "name": "area",
                    "length": 8,
                    "alias": "area",
                    "type": "esriFieldTypeDouble"
                    }
                }]
            }
        },
        {
            "isAltered": false,
            "hasBeenValidated": true,
            "isEnabled": true,
            "name": "Input_Number",
            "value": 1234
        },
        {
            "isAltered": false,
            "hasBeenValidated": true,
            "isEnabled": true,
            "name": "Input_Author"
        },
        {
            "isAltered": false,
            "hasBeenValidated": true,
            "isEnabled": true,
            "name": "Output_Table"
        }
    ]
}

Third Request

In the final validate request, all inputs are provided with a value.

Use dark colors for code blocksCopy
{
    "Input_Features":{
        "isAltered": true,
        "hasBeenValidated": true,
        "isEnabled": true,
        "value": {
            "url": "https://machine.domain.com/webadaptor/rest/services/Hosted/InputFeatures/0"
        }
    },
    "Input_Field":{
        "isAltered": true,
        "hasBeenValidated": true,
        "isEnabled": true,
        "value": {
            "nullable": true,
            "editable": true,
            "name": "area",
            "length": 8,
            "alias": "area",
            "type": "esriFieldTypeDouble"
        }
    },
    "Input_Number":{
        "isAltered": true,
        "hasBeenValidated": false,
        "isEnabled": true,
        "value": 12345678
    },
    "Input_Author":{
        "isAltered": true,
        "hasBeenValidated": false,
        "isEnabled": true,
        "name": "John"
    }
}

Third Response

While all inputs are acceptable, there are some customized message generated this time.

Use dark colors for code blocksCopy
{
    "validationResults":[
        {
            "isAltered": true,
            "hasBeenValidated": true,
            "isEnabled": true,
            "name": "Input_Features",
            "value":{
                "url": "https://machine.domain.com/webadaptor/rest/services/Hosted/InputFeatures/0"
            }
        },
        {
            "isAltered": true,
            "hasBeenValidated": true,
            "isEnabled": true,
            "name": "Input_Field",
            "choiceList": ["area"],
            "filter": {
                "type": "codedValue",
                "list": [{
                    "dataType": "Field",
                    "name": "area",
                    "value": {
                    "nullable": true,
                    "editable": true,
                    "name": "area",
                    "length": 8,
                    "alias": "area",
                    "type": "esriFieldTypeDouble"
                    }
                }]
            }
        },
        {
            "isAltered": true,
            "hasBeenValidated": true,
            "isEnabled": true,
            "name": "Input_Number",
            "value": 12345678
        },
        {
            "isAltered": true,
            "hasBeenValidated": true,
            "isEnabled": true,
            "name": "Input_Author",
            "message": {
                "code": 0,
                "description": "Author value misses department name.",
                "type": "warning"
            }
        },
        {
            "isAltered": false,
            "hasBeenValidated": true,
            "isEnabled": true,
            "name": "Output_Table"
        }
    ],
    "additionalMessages": [
        {
        "code": 0,
        "description": "Author value misses department name.",
        "type": "warning"
        }
    ]
}