Skip to content

Validation of Input Variables

Note

  • Some schema validations are not implemented yet.

eos_designs and eos_cli_config_gen support a wide range of input variables described under the role documentation sections.

Internally the supported data models are described in the proprietary “AVD Schema” format, which is used to perform validation of the input variables at run-time. The same schema is also used to generate the role documentation describing the supported data models.

For details on the schema format see the Schema Details section below.

Automatic Type Conversion

The validation of input variables is performed in most AVD Action Plugins. The validation also supports automatic conversion of variable types, if configured in the schema. The supported types that can be converted from depends on the type to be converted to. The current implementation supports the automatic conversions listed below.

From (convert_types) To (type)
bool, str int
int, str bool
bool, int str

An example of input variable conversion is bgp_as. bgp_as is expected as a string (str) since 32-bit AS numbers can be written with dot-notation such as "65001.10000". Most deployments use 16-bit AS numbers, where the setting bgp_as: 65001 will be interpreted as an integer in YAML, unless it is enclosed in quotes bgp_as: "65001". In the schema for bgp_as the convert_types option is configured to ['int'] which means AVD Action Plugins will automatically convert bgp_as: 65001 to bgp_as: "65001".

Data model deprecations

Deprecation status can be set for every data model and can contain information about when the key will be removed or if it is already removed. The deprecation details can also contain a pointer to a data model to use instead and a URL for further information.

If a deprecated key is set in the inputs, a deprecation warning will be shown. If the deprecation details point to a new data model and this new model is also given in the inputs, there is a conflict leading to validation error to be raised and the task will fail.

If a removed key is set in the inputs, a validation error will be raised and the task will fail.

Validation Options

Schema validation is built in to the central Action plugins used in AVD. Each plugin runs variable type conversion first and then performs validation of the converted data.

By default any data validation issues will trigger errors - blocking further processing. This behavior can be adjusted by setting the variables described below.

Danger

The input variable avd_data_validation_mode now has a default value of error, and while it can be set to warning, this is highly discouraged. All AVD code relies on the validation to ensure valid data, so the code assumes that the data is valid.

If the validation mode is set to warning, execution will continue with invalid data, which can lead to hard-to-read errors or incorrect behavior.

# Validation Mode for AVD input data validation | Optional
# During validation, messages will generated with information about the host(s) and key(s) which failed validation.
# "error" will produce error messages and fail the task.
# "warning" will produce warning messages.
avd_data_validation_mode: < "error" | "warning" | default -> "error" >

Schema Details

The AVD Schema format is a proprietary schema inspired by JSON Schema, Ansible Argument Specification and Arista CloudVision Studios formats.

The AVD Schema has unique features which are not supported or possible with any of the mentioned schema formats. Schema converters can be developed as needed.

Here is an example of a schema fragment for bgp_as:

type: dict
allow_other_keys: true
keys:
  bgp_as:
    display_name: BGP AS
    description: AS number to use to configure overlay when "overlay_routing_protocol" == IBGP
    type: str
    convert_types:
      - int

This fragment will be merged with other fragments during development, to form the complete role schema.

For reference, the full Role Schemas can be found here:

The supported schema options depend on the type of variable that is described. The supported types are int, bool, str, dict and list. The schema does not support mixed types for the same variable, but the automatic type conversion mentioned above can address the usability aspect by helping the user with common mistakes.

The supported schema options for AVD Schema are described in a meta-schema using JSON Schema Draft-7 format. The meta-schema can be seen here. In addition, below is a more detailed description of the supported schema options per variable type.

All schema options (ex. type, max, valid_values) are validated individually, and to pass the validation, the data must conform to all the rules given by the schema options. This means that the validator may report multiple errors about the same piece of data if it violates more than on rule. This also means that a poorly written schema could have conflicting schema options, which may not allow any value. For example type: str schema with min_length: 10 and max_length: 5 would never be satisfied.

The deprecation.new_key field is used for detecting conflicts with old and new data models. To properly detect conflicts the new_key must be a relative path to the new data model or multiple relative paths separated by " or ". Conflict detection only works if the new data model in or below the same dict as the deprecated model.

Schema Options for type int (Integer)

Key Type Required Default Value Restrictions Description
type String True Valid Values:
- "int"
Type of variable using the Python short names for each type.
int for Integer
convert_types List, items: String List of types to auto-convert from.
For type int, auto-conversion is supported from bool and str
  - \<str> String Valid Values:
- "bool"
- "str"
default Integer Default value
max Integer Maximum value
min Integer Minimum value
valid_values List, items: Integer List of valid values
  - \<int> Integer
dynamic_valid_values String Path to variable under the parent dictionary containing valid values.
Variable path use dot-notation and variable path must be relative to the parent dictionary.
If an element of the variable path is a list, every list item will unpacked.
Note that this is building the schema from values in the data being validated!
display_name String Regex Pattern: "^[^\n]+$" Free text display name for forms and documentation (single line)
description String Minimum Length: 1 Free text description for forms and documentation (multi line)
required Boolean Set if variable is required
deprecation Dictionary Deprecation Settings
  warning Boolean True True Emit deprecation warning if key is set
  new_key String Relative path to new key
  remove_in_version String Version in which the key will be removed
  remove_after_date String Date after which the key will be removed
$ref String Reference to Sub Schema using JSON Schema resolver
Example ‘#/keys/mykey’ will resolve the schema for ‘mykey’ under the root dictionary of the current schema
documentation_options Dictionary Special options used for generating documentation
  table String Setting ‘table’ will allow for custom grouping of schema fields in the documentation.
By default each root key has it’s own table. By setting the same table-value on multiple keys, they will be merged to a single table.
If ‘table’ is set on a ‘child’ key, all “ancestor” keys are automatically included in the table so the full path is visible.
The ‘table’ option is inherited to all child keys, unless specifically set on the child.

The meta-schema does not allow for other keys to be set in the schema.

Schema Options for type bool (Boolean)

Key Type Required Default Value Restrictions Description
type String True Valid Values:
- "bool"
Type of variable using the Python short names for each type.
bool for Boolean
convert_types List, items: String List of types to auto-convert from.
For type bool, auto-conversion is supported from int and str
  - \<str> String Valid Values:
- "int"
- "str"
default Boolean Default value
valid_values List, items: Boolean List of valid values
  - \<int> Boolean
dynamic_valid_values String Path to variable under the parent dictionary containing valid values.
Variable path use dot-notation and variable path must be relative to the parent dictionary.
If an element of the variable path is a list, every list item will unpacked.
Note that this is building the schema from values in the data being validated!
display_name String Regex Pattern: "^[^\n]+$" Free text display name for forms and documentation (single line)
description String Minimum Length: 1 Free text description for forms and documentation (multi line)
required Boolean Set if variable is required
deprecation Dictionary Deprecation Settings
  warning Boolean True True Emit deprecation warning if key is set
  new_key String Relative path to new key
  remove_in_version String Version in which the key will be removed
  remove_after_date String Date after which the key will be removed
$ref String Reference to Sub Schema using JSON Schema resolver
Example ‘#/keys/mykey’ will resolve the schema for ‘mykey’ under the root dictionary of the current schema
documentation_options Dictionary Special options used for generating documentation
  table String Setting ‘table’ will allow for custom grouping of schema fields in the documentation.
By default each root key has it’s own table. By setting the same table-value on multiple keys, they will be merged to a single table.
If ‘table’ is set on a ‘child’ key, all “ancestor” keys are automatically included in the table so the full path is visible.
The ‘table’ option is inherited to all child keys, unless specifically set on the child.

The meta-schema does not allow for other keys to be set in the schema.

Schema Options for type str (String)

Key Type Required Default Value Restrictions Description
type String True Valid Values:
- "str"
Type of variable using the Python short names for each type.
str for String
convert_to_lower_case Boolean False Convert string value to lower case before performing validation
convert_types List, items: String List of types to auto-convert from.
For type str, auto-conversion is supported from bool and int
  - \<str> String Valid Values:
- "bool"
- "int"
default String Default value
format String Valid Values:
- "ipv4"
- "ipv4_cidr"
- "ipv6"
- "ipv6_cidr"
- "ip"
- "cidr"
- "mac"
Expected format of the string value.
ipv4 accepts a single IPv4 address (x.x.x.x)
ipv4_cidr accepts an IPv4 CIDR (x.x.x.x/x)
ipv6 accepts a single IPv6 address (x:x::x:x)
ipv6_cidr accepts an IPv6 CIDR (x:x::x:x/x)
ip accepts a single IPv4 or IPv6 address
cidr accepts an IPv4 or IPv6 CIDR
mac accepts a MAC address (xx:xx:xx:xx:xx:xx)
max_length Integer Maximum length
min_length Integer Minimum length
pattern String Format: Regex A regular expression which will be matched on the variable value.
The regular expression should follow the syntax of JSON Schema Regular Expressions
Remember to use double escapes
valid_values List, items: String List of valid values
  - \<str> String
dynamic_valid_values String Path to variable under the parent dictionary containing valid values.
Variable path use dot-notation and variable path must be relative to the parent dictionary.
If an element of the variable path is a list, every list item will unpacked.
Note that this is building the schema from values in the data being validated!
display_name String Regex Pattern: "^[^\n]+$" Free text display name for forms and documentation (single line)
description String Minimum Length: 1 Free text description for forms and documentation (multi line)
required Boolean Set if variable is required
deprecation Dictionary Deprecation Settings
  warning Boolean True True Emit deprecation warning if key is set
  new_key String Relative path to new key
  remove_in_version String Version in which the key will be removed
  remove_after_date String Date after which the key will be removed
$ref String Reference to Sub Schema using JSON Schema resolver
Example ‘#/keys/mykey’ will resolve the schema for ‘mykey’ under the root dictionary of the current schema
documentation_options Dictionary Special options used for generating documentation
  table String Setting ‘table’ will allow for custom grouping of schema fields in the documentation.
By default each root key has it’s own table. By setting the same table-value on multiple keys, they will be merged to a single table.
If ‘table’ is set on a ‘child’ key, all “ancestor” keys are automatically included in the table so the full path is visible.
The ‘table’ option is inherited to all child keys, unless specifically set on the child.

The meta-schema does not allow for other keys to be set in the schema.

Schema Options for type list (List)

Key Type Required Default Value Restrictions Description
type String True Valid Values:
- "list"
Type of variable using the Python short names for each type.
list for List
default List Default value
items Dict Dictionary describing the schema of each list item. This is a recursive schema, so the value must conform to AVD Schema
max_length Integer Maximum length
min_length Integer Minimum length
primary_key String Pattern: ^[a-z][a-z0-9_]*$ Name of a primary key in a list of dictionaries.
The configured key is implicitly required and must have unique values between the list elements
unique_keys List, items: String Item Pattern: ^[a-z][a-z0-9_]*$ Name of a key in a list of dictionaries.
The configured key must have unique values between the list elements.
This can also be a variable path using dot-notation like parent_key.child_key in case of nested lists of dictionaries.
display_name String Regex Pattern: "^[^\n]+$" Free text display name for forms and documentation (single line)
description String Minimum Length: 1 Free text description for forms and documentation (multi line)
required Boolean Set if variable is required
deprecation Dictionary Deprecation Settings
  warning Boolean True True Emit deprecation warning if key is set
  new_key String Relative path to new key
  remove_in_version String Version in which the key will be removed
  remove_after_date String Date after which the key will be removed
$ref String Reference to Sub Schema using JSON Schema resolver
Example ‘#/keys/mykey’ will resolve the schema for ‘mykey’ under the root dictionary of the current schema
documentation_options Dictionary Special options used for generating documentation
  table String Setting ‘table’ will allow for custom grouping of schema fields in the documentation.
By default each root key has it’s own table. By setting the same table-value on multiple keys, they will be merged to a single table.
If ‘table’ is set on a ‘child’ key, all “ancestor” keys are automatically included in the table so the full path is visible.
The ‘table’ option is inherited to all child keys, unless specifically set on the child.

The meta-schema does not allow for other keys to be set in the schema.

Schema Options for type dict (Dictionary)

Key Type Required Default Value Restrictions Description
type String True Valid Values:
- "dict"
Type of variable using the Python short names for each type.
dict for Dictionary
default Dict Default value
keys Dictionary Key Pattern: ^[a-z][a-z0-9_]*$ Dictionary of dictionary-keys in the format {<keyname>: {<schema>}}.
keyname must use snake_case.
schema is the schema for each key. This is a recursive schema, so the value must conform to AVD Schema
dynamic_keys Dictionary Pattern: ^[a-z][a-z0-9_]*$ Dictionary of dynamic dictionary-keys in the format {<variable.path>: {<schema>}}.
variable.path is a variable path using dot-notation and pointing to a variable under the parent dictionary containing dictionary-keys.
If an element of the variable path is a list, every list item will unpacked.
schema is the schema for each key. This is a recursive schema, so the value must conform to AVD Schema
Note that this is building the schema from values in the data being validated!
allow_other_keys Boolean False Allow keys in the dictionary which are not defined in the schema. Custom keys starting with an underscore, like _mycustomkey are exempt from this validation
display_name String Regex Pattern: "^[^\n]+$" Free text display name for forms and documentation (single line)
description String Minimum Length: 1 Free text description for forms and documentation (multi line)
required Boolean Set if variable is required
deprecation Dictionary Deprecation Settings
  warning Boolean True True Emit deprecation warning if key is set
  new_key String Relative path to new key
  remove_in_version String Version in which the key will be removed
  remove_after_date String Date after which the key will be removed
$ref String Reference to Sub Schema using JSON Schema resolver
Allows for easy reuse of schema definitions.
Example ‘#/keys/mykey’ will resolve the schema for ‘mykey’ under the root dictionary of the current schema
documentation_options Dictionary Special options used for generating documentation
  table String Setting ‘table’ will allow for custom grouping of schema fields in the documentation.
By default each root key has it’s own table. By setting the same table-value on multiple keys, they will be merged to a single table.
If ‘table’ is set on a ‘child’ key, all “ancestor” keys are automatically included in the table so the full path is visible.
The ‘table’ option is inherited to all child keys, unless specifically set on the child.

The meta-schema does not allow for other keys to be set in the schema.