---
title: "Read YAML as structured data."
description: "Build named values, lists and nested settings, then separate syntax from meaning."
canonical: https://editmd.app/learn/lessons/yaml-basics/
markdown: https://editmd.app/learn/lessons/yaml-basics.md
status: pre-release, waiting list open
generated: editmd-website
---

# Read YAML as structured data.

Lesson 07 of 12 in Markdown School. Build named values, lists and nested settings, then separate syntax from meaning.

## What is YAML, and when would you use it?

YAML is a text format for structured data. Markdown gives prose headings and lists; YAML gives a program named values, ordered collections and nested records. A `.yaml` or `.yml` file commonly holds settings or metadata. It is not a programming language, and a value cannot perform an action by itself. [YAML specification, introduction](https://yaml.org/spec/1.2.2/#chapter-1-introduction-to-yaml).

For this original exercise, imagine a tool that reads metadata for a garden guide. These names are our invented contract, not settings in editmd:

```yaml
title: Garden guide
draft: true
code: '007'
tags:
  - planning
  - writing
owner:
  name: Mira
```

## Read the shape before editing

`title` names a string. `draft` holds a boolean, while the quoted `"007"` stays text. `tags` holds a sequence; `owner` holds a mapping with its own `name`. Colons separate keys from values. Use spaces for indentation, not tabs. The nesting matters more than visual alignment. [YAML collections](https://yaml.org/spec/1.2.2/#21-collections), [indentation](https://yaml.org/spec/1.2.2/#61-indentation-spaces).

Try reading the example aloud as a record: “The guide has a title, a draft state, a code, two tags and an owner.” If that sentence does not describe your intended data, a successful parse will not fix it.

## Quote text that could be mistaken for something else

```yaml
label: 'Plan: first draft'
reference: '#garden'
code: '007'
draft: false
```

Quoting makes the intended strings explicit. By contrast, `false` here is a boolean. A quoted `"false"` is a string. A receiving tool can reject the wrong type even when the YAML is valid. Comments begin with `#` in the appropriate position; the hash inside the quoted reference belongs to the string. [YAML scalars](https://yaml.org/spec/1.2.2/#23-scalars).

## A small mistake changes the data

```yaml
owner:
name: Mira
```

This can parse, but `name` is a top-level key and `owner` has no supplied value. Indent `name` beneath `owner` to express the relationship. The exercise separates syntax errors from mismatches with its expected fields. Neither check knows whether Mira is the actual owner.

The local practice checker uses YAML 1.2 and deliberately excludes custom tags and aliases. That keeps this beginner exercise bounded; it does not mean those features are forbidden by YAML.

## Practice, then transfer

Add the tags and owner to the starter. Compare the parsed result, then deliberately unindent `name` and check again. Finally, change the fictional owner and choose tags for a different document. Keep the structure; make the content your own. Do not put passwords or private account details in configuration examples.

Sources checked 17 September 2026. Host behavior can change; verify it against the linked documentation when using these examples.

## Exercise

Add two tags and a nested owner mapping. Keep draft a boolean and quote the code so its leading zero stays visible.

## Takeaway

YAML represents data; the receiving tool decides what that data means.

Related guide: https://editmd.app/docs/writing/. All lessons: https://editmd.app/learn.md