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 addresscidr accepts an IPv4 or IPv6 CIDRmac 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 SchemaNote 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.