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:

title: My Video
fps: 30

Indentation (spaces, never tabs) creates nesting:

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

Lists

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

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:

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

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

resolution: [1920, 1080]     # a flow list

Use whichever reads better — they mean the same thing.

Numbers, strings, booleans, null

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:

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

A single line can stay inline:

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-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, sources.yaml, and scenes/<id>.yaml.