Skip to main content

YAML Basics - Quick Reference

YAML (Yet Another Markup Language) is a human-readable format used for configuration files. Flametree uses YAML to define agents, workflows, and integration settings. This quick guide explains the syntax you need to know to work safely and efficiently.

Syntax essentials​

Indentation and structure​

YAML uses spaces to show structure. Do not use tabs. Use a consistent amount of spaces per level (two spaces is common). Items at the same level must align.

root:
  child:
    grandchild: value

Key–value pairs​

Basic mapping is key: value. Values can be scalars (strings, numbers, booleans).

name: John Doe
age: 30
active: true

Strings and quoting​

Unquoted strings are allowed, but quote when you use special characters (:, #, ', "), leading/trailing spaces, or when the value should be preserved exactly.

simple: hello
quoted: "contains: colon"
single_quote: 'can contain "double quotes" safely'

Lists (sequences)​

Lists use hyphens. Indent list items under their parent key.

fruits:
  - apple
  - banana
  - orange

Nested structures (mappings of lists, lists of mappings)​

Combine mappings and sequences to create structured data.

people:
  - name: Alice
    email: alice@example.com
  - name: Bob
    email: bob@example.com

Multi-line text​

Use | to preserve line breaks, or > to fold lines into spaces.

description: |
  First line
  Second line (kept as new line)

summary: >
  This text
  becomes a single line with spaces.

Comments​

Start comments with #. Prefer standalone comment lines for clarity.

# This is a full-line comment
name: John  # Inline comment (use sparingly)

Common mistakes to avoid​

  • Tabs instead of spaces — YAML only supports spaces for indentation.
  • Inconsistent indentation — items at the same level must align.
  • Missing space after : — always use key: value, not key:value.
  • Unescaped special characters — quote strings that include :, #, or special symbols.
  • Misaligned hyphens — make sure list items are correctly indented.

Editing best practices​

Validate before saving​

Always validate YAML syntax before saving. Use an external checker like yamlchecker.com or your code editor’s linter.

Work incrementally​

Apply small edits and test each change. This makes troubleshooting easier and reduces the chance of losing valid configurations.

Keep local backups​

Save complex workflows locally before making changes. If possible, use version control to track your configuration history.

Comment clearly​

Place comments at the start of lines instead of inline. This improves readability and prevents parsing errors.

If a save fails​

If Flametree rejects your update, it usually means there’s a YAML syntax error. Check your structure, fix indentation, and reapply validated changes.

⚠️ Note: If YAML syntax is invalid, Flametree automatically discards the update and restores the last valid version.

Example configuration​

agent:
  name: Sales Assistant
  description: |
    Answers customer questions and schedules demo calls.
  workflow:
    init_state: true
    steps:
      - name: greet
        actions:
          - send_message: "Hello! How can I help?"
      - name: collect_contact
        actions:
          - request_field: HumanFullName
          - request_field: HumanEmail