openHAB

# Standard YAML Syntax

This page introduces the standard YAML syntax used throughout this documentation. It is not a full YAML tutorial. It provides the foundational concepts needed to understand and work with the examples in the YAML Configuration section.

The YAML Composer builds on top of standard YAML 1.2 and adds its own processing features such as custom tags and preprocessing behavior. This page focuses on the core YAML syntax that those features extend.

For more detailed information on the YAML 1.2 syntax supported in openHAB configurations, see the YAML 1.2 specification (opens new window).

# Indentation and Structure

YAML uses indentation to represent structure.

  • Indentation defines the nesting level.
  • Only spaces are allowed.
  • Tabs are not permitted for indentation.
  • All items at the same level must use the same indentation.

openHAB recommends using two spaces per indentation level for consistency.

thing:
  id: myThing
  label: "Example Thing"

Misaligned indentation is one of the most common YAML errors.

# Block Style vs Flow Style

YAML supports two ways of expressing mappings and lists.

Block style is the most readable form.

item:
  type: Switch
  label: "Lamp"
  tags:
    - Light
    - LivingRoom

# Flow Style

Flow style is more compact and resembles JSON. It is functionally identical to block style.

item: { type: Switch, label: "Lamp", tags: [Light, LivingRoom] }

YAML allows block and flow styles to be mixed freely.

# Comments

  • Comments begin with #.
  • Comments continue to the end of the line.
  • Comments may appear on their own line or after a value.
# This is a comment describing the thing
thing:
  id: myThing  # Inline comment
  label: "Example Thing"

# Data Types

YAML defines three fundamental data types: scalars, lists (sequences), and mappings.

# Scalars

Scalars represent simple values such as strings, numbers, booleans, and nulls.

# Booleans

In openHAB YAML files, only the unquoted literals true, True, TRUE, and false, False, FALSE are recognized as boolean values. ON, OFF, Yes, No, enable, and disable are parsed as plain strings. To specify true or false as a string, they must be enclosed in single or double quotes.

# Strings

Strings may be written with or without quotes.

Unquoted strings are allowed only when the value cannot be interpreted as another YAML scalar type such as a number, boolean, or null. In practice, this means unquoted strings should contain letters or simple punctuation, but not values that look like numbers or booleans.

name: KitchenLight
label: Kitchen Light
role: admin

If a value could be parsed as a number, boolean, or null, it must be quoted to ensure it is treated as a string.

string_number: "123"
string_boolean: "true"
string_null: "null"

Quotes are required when:

  • The string contains characters YAML may interpret as syntax.
  • The string contains leading or trailing spaces.
  • The string contains a colon followed by a space, which YAML interprets as a key/value separator.
label: "Kitchen: Main Light"
note: "  This string preserves leading spaces"

Single‑quoted and double‑quoted strings behave differently.

  • Single‑quoted strings treat the content literally.
  • Single‑quoted strings do not process escape sequences.
  • Single‑quoted strings are useful when you want the text to appear exactly as written.
description: 'This string contains \n and it will not be interpreted as a newline'
  • Double‑quoted strings support escape sequences.
  • Double‑quoted strings allow characters such as \n, \t, and \" to be interpreted.
message: "Line one\nLine two"
  • Use single quotes when you want literal text or when the string contains double quotes.
  • Use double quotes when you need escape sequences or when the string contains single quotes and requires escaping.

# Multiline Strings

Multiline strings are used for longer descriptions or scripts.

Use | to preserve line breaks exactly as written.

description: |
  This is a multi-line
  description.
  Line breaks are preserved.

Use > to fold lines into a single paragraph.

notes: >
  This text will be folded
  into a single line,
  with spaces instead of line breaks.
  • | preserves line breaks.
  • > folds single line breaks into spaces.
  • Blank lines are preserved when using >.
  • Indentation under | or > must be consistent and becomes part of the string.

# Numbers

YAML supports numeric scalar values without requiring quotes. A number is interpreted as numeric when it contains only digits, with an optional sign, decimal point, or exponent.

# Valid Examples
positive_integer: 42
negative_integer: -7
decimal_number: 3.1415
negative_decimal: -0.25
scientific_notation: 1.2e6
# When to Use Quotes

Numbers must be quoted if you want them treated as strings:

string_number: "42"
leading_zero_string: "007"

# Null

YAML supports a null value using any of the following forms:

value1: null
value2: Null
value3: NULL
value4: ~
value5:

All of these are interpreted as null.

# Lists (Sequences)

Lists are introduced with a dash (-) at the start of each item.

tags:
  - Light
  - LivingRoom

Flow style is also supported:

tags: [Light, LivingRoom]

# Mappings (Key/Value Pairs)

Mappings define key/value structures.

stateDescription:
  config:
    pattern: "%.1f °C"

Flow style is also supported:

stateDescription: { config: { pattern: "%.1f °C" } }

# How YAML Identifies a Mapping Entry

A mapping entry uses the pattern:

key: value

The space after the colon is required.

text: "Alice: Hello"        # Must be quoted because the colon is followed by a space
url: http://example.com     # Safe unquoted because the colon is not followed by a space

# Anchors and Aliases

Anchors define reusable blocks. Aliases reference those blocks.

defaults: &defaultConfig
  refresh: 60
  geolocation: 1.23456, 7.890123

thing:
  label: "Lamp"
  config: *defaultConfig

For more details, see Anchors and Aliases.

# Merge Keys

YAML merge keys use the <<: syntax to merge mappings.

Note: Although merge keys (<<:) are not defined in YAML 1.2, the YAML Composer includes full support for them. They are a foundational mechanism used throughout the preprocessing system to combine mappings, apply defaults, and build modular configuration structures.

base: &base
  type: Switch
  category: Light

item:
  <<: *base
  label: "Desk Lamp"

Effective structure:

item:
  type: Switch
  category: Light
  label: "Desk Lamp"

For more details, see Merge Keys.

# YAML Tags (Brief Introduction)

YAML supports tags, which change how a value is interpreted. Some tags are built in, and YAML Composer adds several custom tags such as !include, !if, and !remove to enable enhanced features.

A tag can be applied to a simple scalar:

value: !include file.inc.yaml

A tag can also be applied to a mapping. In that form, it applies to everything inside the mapping:

thing: !if
  if: ${thing_enabled}
  then:
    label: Room Light

You will see these custom tags throughout the enhanced YAML configuration.

# Common Pitfalls

  • Using tab characters instead of spaces for indentation.
  • Using inconsistent indentation.
  • Misaligning list items.
  • Omitting quotes around strings containing special characters.
  • Incorrectly nesting mappings.
  • Incorrect indentation under | or > for multiline strings.

If a YAML file fails to load, indentation, quoting, or multiline formatting issues are often the cause.