Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 39 ยท YAML and Config Files

YAML Syntax Basics

Learn YAML from scratch - indentation, key-value mappings, sequences, comments, scalar types and quoting - with a small runnable parser that shows how the text becomes data.

YAML (a recursive name: "YAML is not markup language") is a text format for data that people read and edit by hand. You meet it in Docker Compose files, Kubernetes manifests, GitHub Actions workflows, OpenAPI documents and countless application settings. It describes the same kinds of values as JSON: mappings (objects), sequences (arrays) and scalars (strings, numbers, booleans, null). The difference is the look: instead of braces and quotes, YAML uses indentation and line breaks.

In fact, JSON is almost a subset of YAML 1.2, so a valid JSON file is usually a valid YAML file too. YAML adds comments, multi-line text, references and a lot of shortcuts. Those shortcuts make files pleasant to read and, as you will see in YAML gotchas, occasionally surprising.

About the runnable examples. The Node runner on this site has no npm packages, so there is no real YAML library here. The TryIt below uses a small hand-written parser that understands only the subset taught in this lesson. It is a stand-in for learning: for real work use a maintained library (yaml or js-yaml in JavaScript, PyYAML or ruamel.yaml in Python, serde_yaml in Rust, go-yaml in Go).

Mappings: key and value

A mapping is a set of key: value pairs. The colon must be followed by a space. Each pair sits on its own line, and all pairs of one mapping start at the same column.

YAML
name: Ada Lovelace
born: 1815
active: true

This is the same as the JSON object {"name": "Ada Lovelace", "born": 1815, "active": true}. A mapping inside a mapping is written by indenting the inner pairs:

YAML
person:
  name: Ada Lovelace
  address:
    city: London
    country: UK

Use spaces, never tabs. A tab character in the indentation is a syntax error in YAML. Two spaces per level is the common convention, but any consistent amount works.

Sequences: dash and item

A sequence is a list. Each item begins with a dash and a space, at the same indentation:

YAML
languages:
  - Python
  - Go
  - Rust

Items can be mappings. The dash then acts like the first indentation step for the pairs that follow:

YAML
users:
  - name: ada
    role: admin
  - name: grace
    role: dev

YAML also allows the sequence dashes at the same column as the key (languages: followed by - Python without extra indentation). You will see both styles in the wild.

Comments

A # that starts a line, or follows a space, begins a comment that runs to the end of the line. JSON has no comments at all, which is one of the main reasons people choose YAML for configuration.

YAML
# Server settings
port: 8080   # the default dev port

A # without a space before it, such as in color: red#1, is part of the value.

Scalars and their types

A plain (unquoted) value is read by a schema that guesses its type. In the common YAML 1.2 core schema:

Text Becomes
42, -7 integer
3.14, 1e3 float
true, false boolean
null, ~, or an empty value null
anything else string

Quote a value when you need a string that would otherwise be read as another type. Double quotes support escape sequences such as \n and รฉ; single quotes are literal, and a single quote inside is written twice ('it''s').

YAML
version: "1.10"     # string; unquoted 1.10 would become the number 1.1
answer: '42'        # string
greeting: "Hello\tWorld"
Node.js Parse a YAML subset (stand-in parser)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice what the parser did: "1.10" stayed a string because of the quotes, 8080 became a number, ~ became null, and indentation decided which keys belong to database.

Strings without quotes

Most strings need no quotes at all: title: Hello, world is the string Hello, world. Quotes become necessary when the text:

  • starts with a special character such as *, &, !, %, @, a backtick, [ or {;
  • contains : (colon and space) or # (space and hash);
  • looks like a number, boolean or null but should stay text ("yes", "007", "null");
  • has leading or trailing spaces you want to keep.

Seeing the structure as data

Indentation is the whole grammar, so it helps to picture the tree it builds.

flowchart TD
  root["(mapping)"] --> name["name: shop-api"]
  root --> db["database (mapping)"]
  root --> eps["endpoints (sequence)"]
  db --> host["host: localhost"]
  db --> port["port: 5432"]
  eps --> e1["item 1 (mapping)"]
  eps --> e2["item 2 (mapping)"]

Each level of indentation is one level of nesting in the resulting data.

Node.js From a JavaScript object back to YAML-style text

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The emitter quotes "1.10" on its own because a bare 1.10 would be read back as a number. A real library applies the same safety rule for you, which is why you should generate YAML with a library instead of gluing strings together.

Common mistakes

  • Tabs for indentation. Always spaces.
  • Missing space after the colon. port:8080 is a single string, not a pair.
  • Inconsistent indentation. Siblings must line up exactly; one extra space makes a line a child of the line above.
  • Unquoted values that change type. Versions, zip codes and country codes are the usual victims (see YAML gotchas).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which line is a valid YAML mapping entry?

    A key and its value are separated by a colon followed by a space. Without the space the whole line is one plain string.
  2. 2. What does version: 1.10 produce under the YAML 1.2 core schema?

    An unquoted 1.10 matches the float pattern, so it becomes the number 1.1 and the trailing zero is lost. Quote it to keep the string.
  3. 3. How do you write a comment in YAML?

    A hash sign starts a comment that runs to the end of the line. JSON has no comment syntax at all.
  4. 4. Which character must NOT be used for indentation?

    YAML forbids tab characters in indentation. Any consistent number of spaces works.

Summary

  • YAML uses indentation (spaces only) for nesting, key: value for mappings and - item for sequences.
  • Comments start with #; JSON has none.
  • Unquoted scalars are typed by a schema: numbers, booleans and null are recognised, everything else is a string.
  • Quote anything that must stay a string but looks like another type, and generate YAML with a library.
  • The parser on this page is only a learning stand-in.

Next: Multi-line Text and Flow Style