↓Skip to main content

Tooling for Maintaining YAML Files

·4 mins
Table of Contents

YAML is an essential part of modern software development. It has been an established format for configurations for years, and is unlikely to be replaced for a long time to come. Many, many products now use YAML for configuration, from developer tools and continuous integration pipelines to tools for managing systems like Kubernetes and Ansible.

Ideally, we generate YAML files. This ensures that they are valid, correctly formatted and consistent. However, many YAML files are manually edited, even if they were originally generated by systems. This article describes some standard tools that help us maintain YAML documents, regardless of how they are created or changed.

All of these tools become most effective when they work automatically. We can run them in text editors and with Git hooks that call them when we commit changes to version control. We should also run them in continuous integration pipelines. If they run in continuous integration, we ensure that all of the YAML files in a project are always maintained to the same standard.

Formatting, Linting and Validating YAML #

These tools will work on files that use standard YAML:

You can run them with both Git hooks and on-demand by using a hook manager. Since they are command-line tools, you can also run them as part of continuous integration pipelines.

All of these tools have useful default configurations, so you only need to add configuration files if you need to customize their behavior.

Prettier and schemas also work in modern text editors. These editors can run Prettier on your code. They usually require a plugin, but Zed has Prettier built-in. Editors use the same schemas as check-jsonschema for error checking and autocompletion.

Formatting with Prettier #

Prettier formats files for a wide range of programming languages and data types, including YAML. It is deliberately opinionated, so that every installation of Prettier formats files in exactly the same way, unless users decide to override it.

If your text editor supports Prettier and is configured to format YAML files on save then it works automatically. The Zed editor has Prettier built-in. For other editors, the documentation for the Prettier plugin should explain how to set it up.

Automated code formatting improves software projects for no cost. When we apply the same formatter on every change, the format of the code becomes consistent and predictable, which enables us to rapidly refactor projects. Automatic code formatting also removes the need for commits that only format files.

Linting with yamllint #

The yamllint tool ensures that files are valid YAML. It applies rules that are designed for standard YAML.

If you have YAML files that are templates, you will need to provide a custom configuration for yamllint, or use a specialized tool for the files that are in that format, such as cfn-lint for CloudFormation. For Ansible, we do both: the ansible-lint tool is intended to be used alongside yamllint.

By design, yamllint ignores files with a double file extension, such as .yaml.jinja. These files are likely to be templates.

Validation with check-jsonschema #

The schemas for YAML formats are JSON Schemas. Each schema is a JSON file that describes JSON or YAML. Vendors publish the schemas for their products to the Schema Store. You can create your own schemas.

Modern text editors like Visual Studio Code, JetBrains IDEs, Neovim and Zed use JSON Schemas for autocompletion and error-checking. These editors download schemas for YAML files from the Schema Store, which means that both editors and tools like check-jsonschema apply the same rules.

Visual Studio Code requires the redhat.vscode-yaml extension to support schemas for YAML.

The check-jsonschema tool checks YAML and JSON files against the relevant schema. It includes copies of schemas for popular tools and can use other schemas, including your own schemas. It also provides hooks.