Understanding validation in script tools

You can provide custom behavior for your script tool dialog box, such as enabling and disabling parameters, providing default values, and updating string keywords. By adding Python code, you can do the following:

• Update a parameter filter. Using a field filter, you can create a list of valid field types, such as LONG and DOUBLE. With a string filter, you can set a list of valid keywords. There are six types of filters: Value List, Range, Feature Class, File, Field, and Workspace.
• Provide default values for parameters, such as cell size for rasters.
• Customize warning and error messages that appear on the dialog box.
• Enable or disable a parameter based on values contained in other parameters.

  Note:

  When a parameter is disabled, it will disappear from view on the tool dialog box, and when reenabled, it will reappear. This effect is seen on several system geoprocessing tools such as the Add Field tool where the need for several parameters is dependent on the field type.

• Put parameters in different categories. Categories are expandable window shades with a collection of parameters.

  

• Update the description of output datasets for use in ModelBuilder. By updating the description, subsequent tools in ModelBuilder can see pending data characteristics prior to any tool being run.

How validation works

Validation is performed with a block of Python code that geoprocessing uses to control how the tool dialog box and Python window change based on user input. System tools (those provided by Esri) have always had the capability to react to user input and subsequently modify the tool dialog box as described above.

Validation

Validation means checking that all tool parameters are correct and providing useful messages if they are not. There are two parts to validation:

• The part that you can do by adding code.
• The part that ArcGIS does automatically for you. This part of validation is referred to as internal validation (or basic validation), since it is the basic validation done internally by geoprocessing in ArcGIS.

First, take a look at what internal validation does:

• If a parameter is required, check whether it's empty (nothing entered yet) and, if so, post the Value is required message to the tool dialog box.
• Check that the value the user entered is of the right type (for example, entering a raster instead of a feature class or alphabet characters instead of a number).
• Check filter membership; that is, if you have a Value List filter containing keywords, such as RED, ORANGE, and YELLOW, and you enter BLUE, you'll receive an error message, because BLUE isn't found in the Value List filter.
• Check existence of input datasets.
• Generate a default catalog path for output datasets.
• Update the description of the output data based on a set of rules contained in the special object, Schema.
• Check existence of output datasets against the overwriteOutput environment setting. If the dataset exists and overwriteOutput is false, an error is produced; otherwise, a warning is produced.
• If the parameter is a Field data type, check that the field exists in the associated table.
• Check that the output dataset isn't the same as the input dataset (unless the output is derived, like Add Field).
• For parameters containing linear and areal unit data types, set their default values by examining the corresponding values in ArcGIS AllSource (if running from ArcGIS AllSource).
• If the output is a coverage, grid, or INFO table, check the 13-character file name limit for these datasets.

Internal validation doesn't do the following (but you can with your own validation code):

• Update filters based on interaction with other parameters. For example, if your user enters a point feature class in the first parameter, you want your tool dialog box to display RED, ORANGE, and YELLOW in the third parameter. If a polygon feature class is entered, you want to display BLUE, INDIGO, and VIOLET in the third parameter.
• Enable/Disable parameters.
• Calculate default values.
• Perform any tool-specific parameter interaction.

The code you add works in concert with internal validation as follows:

• You can provide a set of rules that internal validation uses for updating the description of output datasets. These rules are contained in a Schema object.
• You can update filters before internal validation occurs. Drawing on the example above, if a point feature class is entered, you would update the filter to contain RED, ORANGE, and YELLOW. Internal validation checks the value the user entered against the values found in the filter.

You can have your validation code calculate default values, enable and disable parameters, and customize messages. These types of actions have no consequence for internal validation; they only affect the appearance of the tool dialog box.