# YAML Syntax Primer

> A practical YAML syntax primer covering exactly the features Decodx specs use.

# YAML Syntax Primer

You don't need to know all of YAML to author Decodx — just a handful of constructs. This page
covers exactly the ones the spec files use.

## Key–value pairs (mappings)

The building block. A key, a colon, a value:

```yaml
title: My Video
fps: 30
```

Indentation (spaces, never tabs) creates nesting:

```yaml
meta:
  title: My Video
  resolution: [1920, 1080]
```

## Lists

A dash per item — used for the ordered scene list:

```yaml
scenes:
  - intro
  - demo
  - outro
```

## Flow style — inline maps and lists

The same map or list written on one line with braces/brackets. Decodx uses this heavily for compact
source and background definitions:

```yaml
# block style …
background:
  kind: web
  source: dashboard_demo

# … is identical to flow style:
background: { kind: web, source: dashboard_demo }
```

```yaml
resolution: [1920, 1080]     # a flow list
```

Use whichever reads better — they mean the same thing.

## Numbers, strings, booleans, null

```yaml
fps: 30                 # number
title: My Video         # string (quotes optional)
color: "#0b0f19"        # quote strings that start with # so they aren't read as a comment
duration: null          # explicit "no value" — used for auto-timed scenes
avatar: false           # boolean
```

Quote a string when it contains special characters (`:`, `#`, `[`, leading/trailing spaces) or you
want to be explicit.

## Block scalars — multi-line narration

Narration reads best as a block scalar. The `|` keeps line breaks:

```yaml
narration: |
  Welcome to the dashboard.
  Everything you see here updates live.
```

A single line can stay inline:

```yaml
narration: Here is the live dashboard.
```

## Comments and the schema line

`#` starts a comment. The first line of every Decodx file is a special comment that wires up editor
autocomplete and validation:

```yaml
# yaml-language-server: $schema=../../schemas/project.schema.json
```

It's a plain comment to YAML, but the YAML language server reads it to check your file against the
Decodx schema as you type.

## Gotchas

- **Indent with spaces, not tabs** — tabs are a YAML error.
- **Quote `#` values** — `color: #fff` is a comment; write `color: "#fff"`.
- **The scene filename is the id** — do not put an `id:` field inside `scenes/<id>.yaml`; the loader
  injects it, and a stray `id:` is a legible error.

With the syntax down, see the per-file references: [`project.yaml`](./project),
[`sources.yaml`](./sources), and [`scenes/<id>.yaml`](./scenes).