YAML is a friendly data serialization standard that works with all programming languages. While configuration files are often defined in YAML, it can even be used as a programming language, like the workflow language at Google, or Apache Camel K.
It has the advantage of not having any braces, making it lightweight visually. One of the drawbacks is that editing YAML files may not always be easy. For instance, writing a tag at the wrong indentation level can be hard to detect. To help with editing, it is possible to provide a YAML schema that can be leveraged by a large set of integrated development environments (IDEs). Unfortunately, this practice is not widespread. Consequently, users waste time searching for a missing or extra space and browsing documentation.
In this article, you will discover the benefits of providing a YAML schema and how to make it consumable for all your users, making it easier to edit YAML files.
YAML schema
Providing a schema describing the structure of a YAML file type is possible. You might not find the specification easily because it relies on the JSON Schema specifications. YAML schemas allow several IDEs and editors to provide code completion, documentation on hover, and validation of the file, including Eclipse Desktop IDE, Eclipse Che, VS Code, IntelliJ, Emacs, and vim.
For instance, see the code completion example in VS Code for an Apache Camel K integration file in Figure 1.
Figure 2 shows an example of file validation.
Figure 3 shows an example of documentation on hover.
Schema registry
I recommend that you register the schema in the JSON Schema store which is, as far as I know, the largest registry of JSON and YAML schemas. The JSON Schema store is used directly or through the YAML Language Server in several IDEs. It allows an automatic binding of YAML files with their corresponding schema. The biggest advantage is that it is completely transparent for the end user.
To benefit from the JSON Schema store and the built-in integration offered by IDEs, the YAML schema writer needs to set a file name pattern for the YAML files and the schema's users need to respect that pattern. For instance, you can use this kind of file pattern *.myId.yaml. Take care to avoid collision with the existing file name pattern. Colliding with the existing file name patterns will complicate things for your users.
Schema association without a file name pattern
If you do not want to impose a file name pattern, two possibilities remain that benefit from the schema association. Using one of these other methods will add extra effort either for the user or during your tooling maintenance.
Possibility 1: Specific IDE schema association
Most IDEs provide ways to associate a schema to a specific file via preferences. In this case, the burden is on your user.
It is also possible to write a specific extension to auto-associate the schema. The drawback is that specific IDE extensions must be written for each IDE that you want to support. Hopefully, for some of them, there is a specific API to do it. For instance, vscode-yaml is one way you could accomplish this.
Possibility 2: Using in-file declarations
It is possible to use inline metadata to specify the schema corresponding to the file. The following modeline-like format must be used:
# yaml-language-server: $schema=https://my.url.to/the/schema
The main drawback is that this option places a burden on your users. This annotation is also specific to yaml-language-server and not part of the specifications. If you think it would be nice to have it directly inside the YAML specification, please cast your vote here.
The main advantage is that it is available under the hood with all recent IDEs by using the YAML Language Server.
Summary
Providing a YAML schema provides a tremendous benefit to your users. Now you know multiple ways to make your YAML schema easily accessible to all of your users, and make editing these YAML files easier. From here, I hope to see a huge increase in registered schemas on the Schema store!
Last updated: January 25, 2021