Check your YAML for errors with yamllint

Computers thrive on consistency. The reason programming and markup languages (like YAML) have a syntax is because computers cannot derive context from data. In natural languages, we use conventions like commas, quotation marks, and parentheses to help each other parse what we write. However, even without these assistive characters, most of us can still comprehend the communication. Computers don't have that ability, so they rely on rules that dictate what kind of data you provide as input.

Because computers rely on syntax, a whole category of applications has arisen with the sole task of validating input before input reaches the intended application.

A linter is designed to catch errors in data before that data gets processed. This saves you (or your automated workflow) from errors during a critical stage of operation.

The yamllint command is designed, as its name implies, to lint YAML. For Ansible playbooks, there's ansible-lint, and you might think that it would render yamllint useless on your system. However, it's yamllint that enables ansible-lint to report generic YAML violations, and it's a good backup linter when you're on a system that doesn't support or doesn't currently have ansible-lint installed on it.

Install

The easiest way to install yamllint is with pip:

$ python3 -m pip install --user yamllint

Confirm the installation:

$ yamllint --version
yamllint X.Y.Z

Using yamllint

Create this simple playbook. It creates a set of directories on a host. I've included intentional errors so that yamllint will return useful output:

- hosts: localhost
  tasks:
    - name: Create directories
      ansible.builtin.file:
        path: "{{ item }}"
        state: directory
      with_items:
      - '~/Foo'   # this is wrong
      - '~/Bar'   # this is wrong
      - '~/Baz'   # this is wrong

With this playbook saved as standard_dirs.yaml in the directory structure ~/Ansible/playbooks, run the yamllint command:

$ cd ~/Ansible
$ yamllint playbooks/standard_dirs.yaml
playbooks/standard_dirs.yaml
 1:1   warning  missing document start "---" (document-start)
 8:7   error    wrong indentation: expected 8 but found 6 (indentation)
 10:16 error    no new line character at the end of file (new-line-at-end-of-file)

It returns one warning and two errors. Each exception listed starts with a line number and character position. Conveniently, the fix is often explicitly spelled out in the error message.

[ Learn more about Ansible by reading an excerpt from Jesse Keating's eBook Mastering Ansible. ]

Fixing errors

1. The first error occurs on line 1, character 1. Implement the fix by adding --- at the top of the YAML file.
2. The second exception occurs on line 8 at the seventh character. The error text states this is an indentation error, and you fix it by adding an additional two spaces before each dash (-) character. If you don't know why those are errors, read my YAML for Ansible article.
3. The final error is on line 10 at character 16. Fix this by adding a newline character (but not a blank line!) at the end of the file. I find the easiest way to do this is:

   $ sed -i -e '$a\' playbooks/standard_dirs.yaml

Check your work

Run yamllint again to confirm that your fixes satisfy YAML syntax requirements:

$ yamllint playbooks/standard_dirs.yaml
$

No output means no errors, so the changes to the file fixed the errors and warnings.

Lint everything that's lintable

If you're writing code or markup in a language that has a linter available for it, then run the linter. The yamllint command is an invaluable tool when you write YAML. It misses some Ansible-specific warnings, but it's a good fallback command for playbooks, a good command to combine with ansible-lint, and it's essential for any YAML you write.