Skip to main content

YAML Guide

YAML stands for "YAML Ain't a Markup Language", and it's used as the configuration format for several MachineMetrics machine data sources, such as digital IO modules or modbus.

YAML itself has a fairly complex specification, which can be looked up at the official YAML website. To avoid as much complexity as possible, MachineMetrics uses only a small subset of the available YAML syntax.

This guide covers the syntax of YAML that MachineMetrics uses in configs, rather than a specific config specification.

A Basic Example​

The simplest YAML files look like a set of name-value pairs, with each pair on its own line.

version: 1
device: modbus-tcp
host: 10.20.30.40
description: A modbus-enabled PLC
enabled: true

This represents one of the basic YAML data types: a mapping.

All MachineMetrics YAML configurations will start with a mapping like shown above. YAML mappings associate a key (name) with a corresponding value, and each mapping is written on its own line. The key is followed by a colon (:) and one or more spaces, and then followed by the value. Values can be numbers, strings, booleans, or further nested data structures. Strings can be surrounded by single or double quotes, but they are optional.

Common Pitfall

the space between the colon character and the value is important. If there is no space, YAML will interpret the line as a single symbol (like a string), rather than a mapping:

device:modbus-tcp

Comments​

Comments can be inserted into YAML configurations either on their own line, or at the end of other lines. Comments start with a hash (#) symbol.

# This is a YAML file
version: 1
device: modbus-tcp
host: 10.20.30.40  # IP of Machine XYZ
#enabled: true

Nested Mappings​

The values provided in mappings are not limited to numbers, strings, or booleans (which collectively make up scalar types). A value can also be another mapping nested underneath, or a list nested underneath.

version: 1
pets:
  rover:
    species: dog
    age: 6
  kiki:
    species: cat
    age: 10

Nested mappings are placed below the key they're associated with, and indented by one or more spaces. Multiple mappings can be associated with a parent key. In the example, rover and kiki are sub-keys of pets, because they are indented at the same level below the pets key.

The rover and kiki keys each have their own nested mappings. The nested hierarchy of keys creates a logical rouping of items.

Common Pitfall

You must use correct and consistent indentation for the hierarchy of mappings to be interpreted correctly. There is no requirement on the number of spaces you need to indent each level by, as long as you are consistent. We recommend indenting by 2 spaces at each level.

pets:
  rover:
    species: dog
    age: 6
kiki:
  speces: cat
  age: 10

kiki is not indented, so it represents its own top-level group, rather than being a member of the pets group.

pets:
  rover:
    species: dog
    age: 6
 kiki:
   species: cat
   age: 10

rover and kiki have a different number of spaces in their indentation under pets, which is a YAML syntax error. This can be subtle to spot without aid from an enhanced code editor.

pets:
rover:
  species: dog
  age: 6
kiki:
  species: cat
  age: 10

pets, rover, and kiki are all independent groups at the same level. pets is a group that has no items within it.

Lists​

In some cases, configurations need to specify a list of items where elements can be repeated. Mappings are not appropriate in these cases because each entry must be named, and names cannot be repeated within the same group. YAML sequences are used to create these lists, and will be referred to as lists throughout this document.

operations:
  - reverse
  - remove
  - reverse

The mapping operations contains a list of the strings "reverse", "remove", and "reverse".

Each entry in a list begins with an opening dash and space. Each opening dash in the sequence must be indented the same amount. The dashes MAY be indented by the same amount as their parent mapping, or indented further in. For consistency we recommend indenting by 2 spaces.

Lists of Mappings​

List values in a list do not need to be scalars like strings and numbers. They can also be mappings like so:

variables:
  input1:
    - source: pin-0
    - filter: 0.01
    - threshold: 5
    - filter: 0.1

The input1 mapping is a list of items, where each item is a single-entry mapping. This pattern resembles a standard mapping, but allows key names to be "repeated".

Mappings and scalars can be mixed freely in lists:

variables:
  input1:
    - source: pin-0
    - invert
    - threshold: 5
    - falling-edge
    - count

More complex nesting is possible, and used in some MachineMetrics configurations.

variables:
  input1:
    - source: pin-0
    - threshold: 5
    - falling-edge:
        min-width: 0.1
        max-width: 0.8
    - count

The falling-edge item is a mapping with sub-keys defined. Note how the sub-keys are indented in from their parent key.

Common Pitfall

When mixing lists and nested mappings, remember to properly indent sub-keys past the indentation of the parent key name, NOT just the parent key's leading dash.

variables:
  input1:
    - source: pin-0
    - threshold: 5
    - falling-edge:
      min-width: 0.1
      max-width: 0.8
    - count

The min-width and max-width items are not sub-keys of falling-edge. All three items are part of the same unnamed group in a list, and falling-edge is defined as a group that has no items within it.