diff --git a/README.md b/README.md index 9dd9884..5bcab75 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,7 @@ Name | Description [ansible.utils.get_path](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.get_path_filter.rst)|Retrieve the value in a variable using a path [ansible.utils.index_of](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.index_of_filter.rst)|Find the indicies of items in a list matching some criteria [ansible.utils.to_paths](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.to_paths_filter.rst)|Flatten a complex object into a dictionary of paths and values +[ansible.utils.validate](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.validate_filter.rst)|Validate data with provided criteria ### Lookup plugins Name | Description @@ -31,12 +32,19 @@ Name | Description [ansible.utils.get_path](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.get_path_lookup.rst)|Retrieve the value in a variable using a path [ansible.utils.index_of](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.index_of_lookup.rst)|Find the indicies of items in a list matching some criteria [ansible.utils.to_paths](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.to_paths_lookup.rst)|Flatten a complex object into a dictionary of paths and values +[ansible.utils.validate](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.validate_lookup.rst)|Validate data with provided criteria ### Modules Name | Description --- | --- [ansible.utils.fact_diff](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.fact_diff_module.rst)|Find the difference between currently set facts [ansible.utils.update_fact](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.update_fact_module.rst)|Update currently set facts +[ansible.utils.validate](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.validate_module.rst)|Validate data with provided criteria + +### Test plugins +Name | Description +--- | --- +[ansible.utils.validate](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.validate_test.rst)|Validate data with provided criteria diff --git a/docs/ansible.utils.fact_diff_module.rst b/docs/ansible.utils.fact_diff_module.rst index 8f994bb..e727124 100644 --- a/docs/ansible.utils.fact_diff_module.rst +++ b/docs/ansible.utils.fact_diff_module.rst @@ -223,11 +223,6 @@ Examples # changed: [localhost] - - name: Show the difference in yaml format - ansible.utils.fact_diff: - before: "{{ before }}" - after: "{{ before }}" - #### Show the difference between complex object using restconf # ansible_connection: ansible.netcommon.httpapi @@ -235,7 +230,7 @@ Examples # ansible_httpapi_validate_certs: False # ansible_network_os: ansible.netcommon.restconf - - name: Get the current interface config prior ro changes + - name: Get the current interface config prior to changes ansible.netcommon.restconf_get: content: config path: /data/Cisco-NX-OS-device:System/intf-items/phys-items diff --git a/docs/ansible.utils.validate_filter.rst b/docs/ansible.utils.validate_filter.rst new file mode 100644 index 0000000..bafc772 --- /dev/null +++ b/docs/ansible.utils.validate_filter.rst @@ -0,0 +1,171 @@ +.. _ansible.utils.validate_filter: + + +********************** +ansible.utils.validate +********************** + +**Validate data with provided criteria** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Validate ``data`` with provided ``criteria`` based on the validation ``engine``. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsConfigurationComments
+
+ criteria + +
+ raw + / required +
+ 		+ + +
The criteria used for validation of value that represents data options.
+
This option represents the first argument passed in the filter plugin For example config_data|ansible.utils.validate(config_criteria), in this case the value of config_criteria represents this option.
+
For the type of criteria that represents this value refer documentation of individual validator plugins.
+
+
+ data + +
+ raw + / required +
+ 		+ + +
A data that will be validated against criteria.
+
This option represents the value that is passed to filter plugin in pipe format. For example config_data|ansible.utils.validate(), in this case config_data represents this option.
+
For the type of data that represents this value refer documentation of individual validator plugins.
+
+
+ engine + +
+ string +
+ 		+ Default:
"ansible.utils.jsonschema"
+ 		+ +
The name of the validator plugin to use.
+
This option can be passed in lookup plugin as a key, value pair For example config_data|ansible.utils.validate(config_criteria, engine='ansible.utils.jsonschema'), in this case the value ansible.utils.jsonschema represents the engine to be use for data valdiation. If the value is not provided the default value that is ansible.uitls.jsonschema will be used.
+
The value should be in fully qualified collection name format that is <org-name>.<collection-name>.<validator-plugin-name>.
+
+
+ + +Notes +----- + +.. note:: + - For the type of options ``data`` and ``criteria`` refer the individual ``validate`` plugin documentation that is represented in the value of ``engine`` option. + - For additional plugin configuration options refer the individual ``validate`` plugin documentation that is represented by the value of ``engine`` option. + - The plugin configuration option can be either passed as *key=value* pairs within filter plugin or environment variables. + - The precedence of the ``validate`` plugin configurable option is the variable passed within filter plugin as *key=value* pairs followed by the environment variables. + + + +Examples +-------- + +.. code-block:: yaml + + - name: set facts for data and criteria + set_fact: + data: "{{ lookup('file', './validate/data/show_interfaces_iosxr.json')}}" + criteria: "{{ lookup('file', './validate/criteria/jsonschema/show_interfaces_iosxr.json')}}" + + - name: validate data in json format using jsonschema with by passing plugin configuration variable as key/value pairs + ansible.builtin.set_fact: + data_validilty: "{{ data|ansible.utils.validate(criteria, engine='ansible.utils.jsonschema', draft='draft7') }}" + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this filter: + +.. raw:: html + + + + + + + + + + + + +
KeyReturnedDescription
+
+ _raw + +
+ - +
+ 		+
If data is valid returns empty list
+
If data is invalid returns list of errors in data
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- Ganesh Nalawade (@ganeshrn) + + +.. hint:: + Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. diff --git a/docs/ansible.utils.validate_lookup.rst b/docs/ansible.utils.validate_lookup.rst new file mode 100644 index 0000000..4e468a7 --- /dev/null +++ b/docs/ansible.utils.validate_lookup.rst @@ -0,0 +1,177 @@ +.. _ansible.utils.validate_lookup: + + +********************** +ansible.utils.validate +********************** + +**Validate data with provided criteria** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Validate ``data`` with provided ``criteria`` based on the validation ``engine``. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsConfigurationComments
+
+ criteria + +
+ raw + / required +
+ 		+ + +
The criteria used for validation of value that represents data options.
+
This option represents the second argument passed in the lookup plugin For example lookup(config_data, config_criteria, engine='ansible.utils.jsonschema'), in this case the value of config_criteria represents this option.
+
For the type of criteria that represents this value refer documentation of individual validate plugins.
+
+
+ data + +
+ raw + / required +
+ 		+ + +
A data that will be validated against criteria.
+
This option represents the value that is passed to lookup plugin as first argument. For example lookup(config_data, config_criteria, engine='ansible.utils.jsonschema'), in this case config_data represents this option.
+
For the type of data that represents this value refer documentation of individual validate plugins.
+
+
+ engine + +
+ string +
+ 		+ Default:
"ansible.utils.jsonschema"
+ 		+ +
The name of the validate plugin to use.
+
This option can be passed in lookup plugin as a key, value pair For example lookup(config_data, config_criteria, engine='ansible.utils.jsonschema'), in this case the value ansible.utils.jsonschema represents the engine to be use for data valdiation. If the value is not provided the default value that is ansible.uitls.jsonschema will be used.
+
The value should be in fully qualified collection name format that is <org-name>.<collection-name>.<validate-plugin-name>.
+
+
+ + +Notes +----- + +.. note:: + - For the type of options ``data`` and ``criteria`` refer the individual ``validate`` plugin documentation that is represented in the value of ``engine`` option. + - For additional plugin configuration options refer the individual ``validate`` plugin documentation that is represented by the value of ``engine`` option. + - The plugin configuration option can be either passed as *key=value* pairs within lookup plugin or task or environment variables. + - The precedence the ``validate`` plugin configurable option is the variable passed within lookup plugin as *key=value* pairs followed by task variables followed by environment variables. + + + +Examples +-------- + +.. code-block:: yaml + + - name: set facts for data and criteria + set_fact: + data: "{{ lookup('file', './validate/data/show_interfaces_iosxr.json')}}" + criteria: "{{ lookup('file', './validate/criteria/jsonschema/show_interfaces_iosxr.json')}}" + + - name: validate data in json format using jsonschema with lookup plugin by passing plugin configuration variable as key/value pairs + ansible.builtin.set_fact: + data_criteria_checks: "{{ lookup(data, criteria, engine='ansible.utils.jsonschema', draft='draft7') }}" + + - name: validate data in json format using jsonschema with lookup plugin by passing plugin configuration variable as task variable + ansible.builtin.set_fact: + data_criteria_checks: "{{ lookup('ansible.utils.validate', data, criteria, engine='ansible.utils.jsonschema', draft='draft7') }}" + vars: + ansible_validate_jsonschema_draft: draft3 + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this lookup: + +.. raw:: html + + + + + + + + + + + + +
KeyReturnedDescription
+
+ _raw + +
+ - +
+ 		+
If data is valid returns empty list
+
If data is invalid returns list of errors in data
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- Ganesh Nalawade (@ganeshrn) + + +.. hint:: + Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. diff --git a/docs/ansible.utils.validate_module.rst b/docs/ansible.utils.validate_module.rst new file mode 100644 index 0000000..cf9546b --- /dev/null +++ b/docs/ansible.utils.validate_module.rst @@ -0,0 +1,175 @@ +.. _ansible.utils.validate_module: + + +********************** +ansible.utils.validate +********************** + +**Validate data with provided criteria** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Validate data with provided criteria based on the validation engine. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ criteria + +
+ raw + / required +
+ 		+ +
The criteria used for validation of data. For the type of criteria refer documentation of individual validate plugins.
+
+
+ data + +
+ raw + / required +
+ 		+ +
A data that will be validated against criteria. For the type of data refer documentation of individual validate plugins
+
+
+ engine + +
+ string +
+ 		+ Default:
"ansible.utils.jsonschema"
+ 		+
The name of the validate plugin to use. The engine value should follow the fully qualified collection name format that is <org-name>.<collection-name>.<validate-plugin-name>.
+
+
+ + +Notes +----- + +.. note:: + - For the type of options ``data`` and ``criteria`` refer the individual ``validate`` plugin documentation that is represented in the value of ``engine`` option. + - For additional plugin configuration options refer the individual ``validate`` plugin documentation that is represented by the value of ``engine`` option. + - The plugin configuration option can be either passed as task or environment variables. + - The precedence the ``validate`` plugin configurable option is task variables followed by the environment variables. + + + +Examples +-------- + +.. code-block:: yaml + + - name: set facts for data and criteria + set_fact: + data: "{{ lookup('file', './validate/data/show_interfaces_iosxr.json')}}" + criteria: "{{ lookup('file', './validate/criteria/jsonschema/show_interfaces_iosxr.json')}}" + + - name: validate data in with jsonschema engine (by passing task vars as configurable plugin options) + ansible.utils.validate: + data: "{{ data }}" + criteria: "{{ criteria }}" + engine: ansible.utils.jsonschema + vars: + ansible_jsonschema_draft: draft7 + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ errors + +
+ list +
+ 		when data value is invalid +
The list of errors in data based on the criteria.
+
+
+
+ msg + +
+ string +
+ 		always +
The msg indicates if the data is valid as per the criteria.
+
In case data is valid return success message all checks passed
+
In case data is invalid return error message Validation errors were found along with more information on error is available.
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- Bradley Thornton (@cidrblock) +- Ganesh Nalawade (@ganeshrn) diff --git a/docs/ansible.utils.validate_test.rst b/docs/ansible.utils.validate_test.rst new file mode 100644 index 0000000..7e6010b --- /dev/null +++ b/docs/ansible.utils.validate_test.rst @@ -0,0 +1,171 @@ +.. _ansible.utils.validate_test: + + +********************** +ansible.utils.validate +********************** + +**Validate data with provided criteria** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Validate ``data`` with provided ``criteria`` based on the validation ``engine``. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsConfigurationComments
+
+ criteria + +
+ raw + / required +
+ 		+ + +
The criteria used for validation of value that represents data options.
+
This option is passed to the test plugin as key, value pair For example config_data is ansible.utils.validate(criteria=criteria), in this case the value of criteria key represents this criteria for data validation.
+
For the type of criteria that represents this value refer documentation of individual validate plugins.
+
+
+ data + +
+ raw + / required +
+ 		+ + +
A data that will be validated against criteria.
+
This option represents the value that is passed to test plugin as check. For example config_data is ansible.utils.validate(criteria=criteria, in this case config_data represents this option.
+
For the type of data that represents this value refer documentation of individual validate plugins.
+
+
+ engine + +
+ string +
+ 		+ Default:
"ansible.utils.jsonschema"
+ 		+ +
The name of the validate plugin to use.
+
This option can be passed in test plugin as a key, value pair For example config_data is ansible.utils.validate(engine='ansible.utils.jsonschema', criteria=criteria), in this case the value of engine key represents the engine to be use for data valdiation. If the value is not provided the default value that is ansible.uitls.jsonschema will be used.
+
The value should be in fully qualified collection name format that is <org-name>.<collection-name>.<validate-plugin-name>.
+
+
+ + +Notes +----- + +.. note:: + - For the type of options ``data`` and ``criteria`` refer the individual ``validate`` plugin documentation that is represented in the value of ``engine`` option. + - For additional plugin configuration options refer the individual ``validate`` plugin documentation that is represented by the value of ``engine`` option. + - The plugin configuration option can be either passed as *key=value* pairs within test plugin or set as environment variables. + - The precedence the ``validate`` plugin configurable option is the variable passed within test plugin as *key=value* pairs followed by task variables followed by environment variables. + + + +Examples +-------- + +.. code-block:: yaml + + - name: set facts for data and criteria + set_fact: + data: "{{ lookup('file', './validate/data/show_interfaces_iosxr.json')}}" + criteria: "{{ lookup('file', './validate/criteria/jsonschema/show_interfaces_iosxr.json')}}" + + - name: validate data in json format using jsonschema with test plugin + ansible.builtin.set_fact: + is_data_valid: "{{ data is ansible.utils.validate(engine='ansible.utils.jsonschema', criteria=criteria, draft='draft7') }}" + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this test: + +.. raw:: html + + + + + + + + + + + + +
KeyReturnedDescription
+
+ _raw + +
+ - +
+ 		+
If data is valid return true
+
If data is invalid return false
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- Ganesh Nalawade (@ganeshrn) + + +.. hint:: + Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.