Working with YAML

While YAML (yaml.org (opens new window)) is a human-friendly format compared to XML and JSON, and is the recommended format for configuration files in BlackLab, there are a few things you should be aware of.

When to quote values

Most values in YAML don't need to be quoted, e.g.:

a: xyz
b: 123
c: 1 + 2 = 3

However, some characters have special significance in YAML. These are:

:{}[],&*#?|-<>=!%@\)

If a value contains such a character, it is generally safest put quotes around it, e.g.:

d: "x:y:z"
e: "[test]"
f: "@attribute"

Lists vs. objects

Sometimes a value needs to be a list, even if that list only has one element. For example, to do string processing on a value (see Processing values), you have to specify a list of processing steps (each of which is an object), even if there's only one step (note the dash):

process:
- action: replace
  find: apple
  replace: pear

Here, "process" is a list containing one element: an object with three keys (action, find and replace). This is correct.

Howerver, it is easy to accidentally type this:

process:
  action: replace
  find: apple
  replace: pear

Here, "process" is not a list of processing step objects, but a single object.

Validating, syntax highlighting

You can validate YAML files online, for example using YAMLlint (opens new window). This can help check for mistakes and diagnose any resulting problems.

Many text editors can also help you edit YAML files by highlighting characters with special meaning, so you can clearly see e.g. when a value should be quoted. Two examples are Sublime Text and Notepad++. If support for YAML highlighting isn't built-in to your favourite editor, it is often easy to install as a plugin. We recommend using an editor with syntax highlighting to edit your YAML files.

More information

To learn more about YAML, see the official site (opens new window) or this introduction (opens new window).