Several months ago, I received a little consulting job that required me to create a structured report.Naturally, I wrote a custom application called dokumentatorin to convert YAML files to other formats. The transformed files can be processed further by tools like Pandoc to generate nice-looking documents. Although the generated reports were guaranteed to look beautiful, I still had to create dozens of YAML files and fill them with data. My editor of choice for such a task is Visual Studio Code.

So there I was, creating the first YAML file and adding about ten fields to it. Some of the fields contained simple strings, while others expected a certain format. After finishing the third file, I decided that I could not possibly continue like this. I am used to all of my code editors supporting me whenever I edit structured data or code. I wanted to have the same experience for these YAML files. Otherwise, I could have just used some office text editor like a sane person.

My tool that processes the YAML files could already validate the files using a JSON Schema. So why not reuse the schema that I already built? In general, a JSON Schema is used to describe and validate the structure of a JSON document while also using the JSON data format itself. The following is an example JSON Schema for a person with a name, an age, and a favorite ice cream flavor. Each field has a type and some annotations used to validate and describe the data and mark which fields are required.

{
  "type": "object",
  "description": "A person.",
  "additionalProperties": false,
  "properties": {
    "name": {
      "type": "string",
      "description": "First and last name of the person."
    },
    "age": {
      "type": "integer",
      "description": "Age of the person.",
      "minimum": 0
    },
    "iceCreamFlavor": {
      "type": "string",
      "description": "Favourite ice cream flavor of the person.",
      "enum": ["vanilla", "chocolate", "strawberry", "blue"]
    }
  },
  "required": ["name", "age", "iceCreamFlavor"]
}

I spent some time searching around and found out that with the help of the YAML extension for Visual Studio Code and some settings, I could build my own autocomplete and validation using my JSON Schema. To demonstrate this imagine a directory structured like this:

• .vscode/
  • settings.json
• data/
  • john.yaml
• schema.json

I want the JSON Schema defined above and stored in the schema.json file to provide autocompletion and validation for all YAML files in the data directory. To accomplish this, I have to add the following setting to the .vscode/settings.json file.

{
  "yaml.schemas": {
    "schema.json": "data/*.yaml"
  }
}

Now I can press CTRL + Space in the john.yaml file and get suggestions for the complete structure defined in the JSON Schema.

In my opinion, this feature is powerful and can be used in many situations. It certainly made my job a lot easier and prevented some mistakes.