| 1 |
# Schemas for Ansible and its related tools |
| 2 |
|
| 3 |
[](https://github.com/ansible-community/schemas/actions/workflows/task.yml) |
| 4 |
[](https://github.com/psf/black) |
| 5 |
[](LICENSE) |
| 6 |
|
| 7 |
## About Schemas |
| 8 |
|
| 9 |
This project aims to generate JSON/YAML validation schemas for Ansible files |
| 10 |
such as playbooks, tasks, requirements, meta or vars and also for Molecule |
| 11 |
configuration. |
| 12 |
|
| 13 |
Keep in mind that these schemas will limit your freedom of choice regarding the |
| 14 |
syntax you can use to write Ansible tasks as they do not allow some historical |
| 15 |
forms which are still allowed by Ansible itself. |
| 16 |
|
| 17 |
Not any file accepted by Ansible will pass these schemas but we do expect that |
| 18 |
any file that passed these schemas should be accepted by Ansible. |
| 19 |
|
| 20 |
- YAML 1.2 booleans are required as `true` or `false`, while Ansible itself |
| 21 |
allows you to use more relaxed forms like `yes` or `no`. |
| 22 |
- Inline actions are not allowed, as schema cannot validate them |
| 23 |
- Non-built-in modules must be called using `action:` blocks |
| 24 |
- Module arguments are not yet verified but we plan to implement it |
| 25 |
- Out schemas are strict about usage of jinja2 templating and require `{{` on |
| 26 |
arguments declared as **explicit**, which forbid the use of `{{` on those |
| 27 |
marked as **implicit**. See the section below for details. |
| 28 |
|
| 29 |
As these schemas are still experimental, creating pull requests to improve the |
| 30 |
schema is of much greater help. Though you are still welcome to report bugs but |
| 31 |
expect them to take a long time until someone finds time to fix them. |
| 32 |
|
| 33 |
If you want to help improve the schemas, have a look at the |
| 34 |
[development documentation](CONTRIBUTING.md). |
| 35 |
|
| 36 |
## Schema Bundle |
| 37 |
|
| 38 |
We are currently migrating towards a single [ansible.json](/f/ansible.json) |
| 39 |
schema bundle, one that contains subschema definitions for all the supported |
| 40 |
file types. |
| 41 |
|
| 42 |
To configure your validator or editor to use the bundle, use the new URLs below, |
| 43 |
the part after the `#` in the URLs is essential for informing the loader about |
| 44 |
which subschema to use. You can also look at our |
| 45 |
[settings.json](.vscode/settings.json) to understand how to configure the |
| 46 |
[vscode-yaml](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) |
| 47 |
extension. |
| 48 |
|
| 49 |
- [playbook subschema url](https://raw.githubusercontent.com/ansible/ansible-lint/main/src/ansiblelint/schemas/ansible.json#/$defs/playbook) |
| 50 |
- [tasks subschema uri](https://raw.githubusercontent.com/ansible/ansible-lint/main/src/ansiblelint/schemas/ansible.json#/$defs/tasks) |
| 51 |
|
| 52 |
## Jinja2 implicit vs explicit templating |
| 53 |
|
| 54 |
While Ansible might allow you to combine implicit and explicit templating, our |
| 55 |
schema will not. Our schemas will only allow you to use the recommended form, |
| 56 |
either by forbidding you to use the curly braces on implicit ones or forcing you |
| 57 |
to add them on explicit ones. |
| 58 |
|
| 59 |
Examples: |
| 60 |
|
| 61 |
```yaml |
| 62 |
- name: some task |
| 63 |
command: echo 123 |
| 64 |
register: result |
| 65 |
vars: |
| 66 |
become_method_var: sudo |
| 67 |
become_method: become_method_var # <-- schema will not allow this |
| 68 |
# become_method: "{{ become_method_var }}" # <-- that is allowed |
| 69 |
``` |
| 70 |
|
| 71 |
### How to find if a field is implicit or explicit? |
| 72 |
|
| 73 |
Run assuming that your keyword is `no_log`, you can run |
| 74 |
`ansible-doc -t keyword no_log`, which will give you the following output: |
| 75 |
|
| 76 |
```yaml |
| 77 |
failed_when: |
| 78 |
applies_to: |
| 79 |
- Task |
| 80 |
description: |
| 81 |
Conditional expression that overrides the task's normal 'failed' status. |
| 82 |
priority: 0 |
| 83 |
template: implicit |
| 84 |
type: list |
| 85 |
``` |
| 86 |
|
| 87 |
As you can see the `template` field tells you if is implicit or explicit. |
| 88 |
|
| 89 |
Being more restrictive, schema protects you from common accidents, like writing |
| 90 |
a simple string in an explicit field. That will always evaluate as true instead |
| 91 |
of being evaluated as a jinja template. |
| 92 |
|
| 93 |
## Activating the schemas |
| 94 |
|
| 95 |
At this moment installing |
| 96 |
[Ansible VS Code Extension by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.ansible) |
| 97 |
will activate these schemas. The file patterns used to trigger their use can be |
| 98 |
seen |
| 99 |
[here](https://github.com/ansible-community/vscode-ansible/blob/master/package.json#L44-L94) |
| 100 |
|
| 101 |
Because these schemas are generic, you can easily use them with any validators |
| 102 |
that support them. |