See your agents built, governed and running in a 30-minute walkthrough. Book a demo →
← All posts

How to Read and Write YAML

Maps, lists, indentation, quotes and multi-line text, in eight short lessons you can edit, with the JSON a program reads updating as you type.

Sriram 2 min read
A YAML file on a card, with indentation guides and labels for map, list and nested, under the title How to read and write YAML.

Workflows, Kubernetes manifests, CI pipelines and agent configs are all written in YAML. YAML is JSON written for people: the same maps, lists, strings and numbers, with indentation instead of braces.

The quickest way to learn it is to watch what a program reads. Edit the YAML on the left and the JSON on the right updates as you type.

Maps. key: value pairs. The space after the colon is required. Order does not matter.

YAML
What a program reads (JSON)
{
  "name": "process-order",
  "version": 3,
  "active": true,
  "owner": null
}

Lists. Each item starts with "- ". Items are in order, and can be any type.

YAML
What a program reads (JSON)
{
  "secrets": [
    "paymentKey",
    "shopToken"
  ],
  "retries": [
    1,
    5,
    30
  ]
}

Nesting. Indentation, in spaces, puts a key inside another. Two spaces per level is the convention. Tabs are not allowed.

YAML
What a program reads (JSON)
{
  "document": {
    "namespace": "shop",
    "name": "process-order"
  },
  "timeout": {
    "after": {
      "minutes": 30
    }
  }
}

List of maps. The pattern every workflow uses: a list whose items are maps. The keys after "- " belong to the same item, so they line up.

YAML
What a program reads (JSON)
{
  "do": [
    {
      "price": {
        "set": {
          "total": 42
        }
      }
    },
    {
      "charge": {
        "call": "http",
        "with": {
          "method": "post"
        }
      }
    }
  ]
}

Inline. Flow style: { } for a map and [ ] for a list, on one line. Same data, shorter. Handy for small values.

YAML
What a program reads (JSON)
{
  "delay": {
    "seconds": 2
  },
  "tags": [
    "orders",
    "payments"
  ],
  "limit": {
    "attempt": {
      "count": 3
    }
  }
}

Strings. Most strings need no quotes. Quote them when YAML would otherwise read a number, a boolean, or a colon followed by a space.

YAML
What a program reads (JSON)
{
  "plain": "Process an order",
  "version": "1.10",
  "unquoted": 1.1,
  "title": "Order: paid",
  "expr": "${ { id: .orderId } }"
}

Multi-line. | keeps the line breaks (good for scripts). > folds the lines into one (good for long text).

YAML
What a program reads (JSON)
{
  "code": "print(\"one\")\nprint(\"two\")\n",
  "summary": "Validates the order, charges the card and ships it.\n"
}

Fix me. This one does not parse. Read the error, then fix it: one quote is enough.

YAML
What a program reads (JSON)
bad indentation of a mapping entry (3:15)

 1 | document:
 2 |   name: process-order
 3 |   title: Order: paid
-------------------^

Reading a YAML file

Four questions get you through any file:

  1. Who owns this line? The nearest line above it with less indentation. Indentation is the structure.
  2. Is it a list item? A line starting with - is one item of a list. Every key indented under it, lined up with the first key after the dash, belongs to the same item.
  3. Is the value here, or below? key: value holds a value on the same line. key: with nothing after it means the value is the indented block below.
  4. Is it text, or something else? true, false, null and numbers are read as those types. Quotes force text. | and > start multi-line text.

Writing rules

  • Spaces, never tabs. Two per level, and the same number everywhere in the file.
  • A space after every colon. key:value is one string, not a key and a value.
  • Quote what looks like something else: versions ('1.10', or it becomes 1.1), cron lines ('0 * * * *'), and any value containing : or starting with {, [, *, &, !, % or @.
  • Quote expressions that contain : . In a workflow, as: '${ { id: .orderId } }' needs quotes; in: ${ .items } does not.
  • Comments start with #, after a space if they follow a value.

Gotchas

You writeA program readsFix
version: 1.10the number 1.1version: '1.10'
title: Order: paida parse errortitle: 'Order: paid'
zip: 01234the number 1234zip: '01234'
country: NOfalse, in YAML 1.1 parsers such as PyYAMLcountry: 'NO'
on: pushtrue: push, in YAML 1.1 parsers'on': push
a tab before a keya parse errortwo spaces

The last two depend on the parser. YAML 1.2, which the playground above uses, reads NO and on as text; older YAML 1.1 parsers read them as booleans. Quoting works in both.

Next

Now read a real schema: CNCF Workflow DSL, Explained shows the whole workflow language as a tree you can open key by key.

Sources