Debian Codegraph @

src/ansiblelint/schemas/README.md

raw
1 # Schemas for Ansible and its related tools
2
3 [![ci](https://github.com/ansible-community/schemas/actions/workflows/task.yml/badge.svg)](https://github.com/ansible-community/schemas/actions/workflows/task.yml)
4 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
5 [![Repository License: MIT](https://img.shields.io/badge/license-MIT-brightgreen.svg)](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.