capable.core212.validate_vars

Validate playbook variables and facts against an argument specification

This module acts similarly to M(ansible.builtin.validate_argument_spec) but focuses on validating any variable in the current task scope without an intermediate ‘argument_spec’ dictionary.

It supports deep type checking (nested dicts/lists), relational validation (mutually exclusive, required together, required one of, required if, required by), custom Jinja2 conditions, and dynamic schema resolution.

It is a pure validator. It never supplies, injects, or substitutes values. An absent variable that is not required is simply skipped.

The validated values are intentionally not returned by the module. Variable values may contain secrets (for example passwords or tokens) and the task result can be logged or displayed.

Basic types (str, int, float, bool, list, dict) are validated strictly with no coercion. Coercing types (str_int, str_float, str_bool) accept a string (or the already-correct target) and normalise it during validation. The any type accepts any value.

Variable values are resolved with Ansible’s templating rules, including partially interpolated strings. Explicitly unsafe or untrusted strings remain data; the plugin never grants template trust to values.

Schema attributes, relational definitions and error messages are ordinary task arguments, templated by Ansible before the action runs. They are not templated a second time by the plugin.

Error messages can contain invalid values. Use no_log=true on the task when validating secrets. With no_log, the failure summary msg is value-free to protect Ansible’s console error summary. Detailed argument_errors remain available in the private registered result; do not print them.

Relational presence means a name exists in the current variable scope, including inventory variables, role defaults, magic variables and names not declared in the schema. Null is present and is subject to strict type checking; use any to accept it. An omitted value is absent. A type failure does not make a variable absent.

Relational comparisons use successfully validated, normalized schema values when available. Otherwise they use resolved, uncoerced scope values. Equality follows Python semantics, including true == 1.

Relational groups must be nonempty lists of names; duplicate names are ignored. A singleton group is valid.

Validation runs in check mode, never changes variables, and an empty specification succeeds.

Parameters

`<variable_name>`

Type: dict

The name of the variable to be validated. The schema attributes are nested directly under the variable name. Any top-level key that is not one of the reserved relational rule keys (mutually_exclusive, required_together, required_one_of, required_if, required_by) is treated as a variable name. Names are literal scope keys, not dotted paths; use options for nested dict keys. Schema attributes must be recognized; options requires type=dict and elements requires type=list. Malformed schemas are rejected even for absent variables or empty containers.

`mutually_exclusive`

Type: list

List of variable groups where at most one variable per group may be present. Top level only.

`required_by`

Type: dict

Dictionary mapping a variable to its dependent variable(s). If the key variable is present, all of its dependents must be present. Top level only.

`required_if`

Type: list

List of Ansible-style tuples (variable, value, required_variables[, any_bool]). When variable equals value, the listed required_variables are required. If the optional fourth element is true, at least one of them is required instead of all. Top level only.

`required_one_of`

Type: list

List of variable groups where at least one variable per group must be provided. Top level only.

`required_together`

Type: list

List of variable groups where if one is provided, all must be provided. Top level only.

Examples

- name: Validate basic variables (strict types)
  capable.core212.validate_vars:
    user_name:
      type: str
      required: true
    user_age:
      type: int

- name: Coerce stringly-typed input
  capable.core212.validate_vars:
    port:
      type: str_int
    debug_enabled:
      type: str_bool

- name: Validate variables with custom and deep logic
  capable.core212.validate_vars:
    db_port:
      type: int
      custom_validation:
        - condition: this > 1024
          error_message: "Port must be greater than 1024"
    config:
      type: dict
      options:
        backend:
          type: str
          required: true

- name: Validate relational logic
  capable.core212.validate_vars:
    mode_a:
      type: bool
    mode_b:
      type: bool
    state:
      type: str
    name:
      type: str
    mutually_exclusive:
      - ['mode_a', 'mode_b']
    required_if:
      - ['state', 'present', ['name']]

Return Values

`argument_errors`

Type: list · Returned: failed

A list of argument validation errors.

Authors

Kirill Satarin (@kksat)