YAML Basics

This guide covers the fundamental YAML syntax and patterns used throughout Compozy configurations. Understanding these basics is essential for creating effective workflows, agents, and tools.

YAML Fundamentals

Data Types

Strings, numbers, booleans, and null values

Collections

Lists (arrays) and maps (objects)

Templates

Go template syntax for dynamic values

Basic Data Types

YAML supports several data types that are commonly used in Compozy configurations:

# Simple strings
name: "Compozy"
description: 'A workflow orchestration engine'

# Multiline strings
multiline: |
  This is a multiline string
  that preserves line breaks

# Folded strings
folded: >
  This is a folded string
  that converts line breaks to spaces

String patterns are used throughout Compozy for identifiers, descriptions, and template values. Use quotes when your string contains special characters or starts with numbers.

Template Integration

Template Syntax

Templates use Go template syntax to create dynamic values:

Value Substitution

Simple variable replacement

Functions

Built-in template functions

Conditionals

Dynamic logic and defaults

Basic Template Substitution

# Simple value substitution
message: "Hello {{ .user.name }}"

# Nested object access
city: "{{ .workflow.input.location.city }}"

# Array indexing
first_item: "{{ .items[0] }}"

# Task output reference
result: "{{ .tasks.previous.output }}"

Template expressions are wrapped in {{ }} and can access any data from the workflow context, including inputs, environment variables, and task outputs.

Best Practices

Consistent Indentation
Use 2 spaces for indentation consistently throughout your files
Meaningful IDs
Use descriptive, kebab-case identifiers for resources and tasks
Proper Quoting
Quote strings that contain special characters or start with numbers
Clear Comments
Add comments to explain complex configurations or business logic

Keep templates simple and readable.

Complex logic should be handled in code, not in templates.

Template Best Practices

# ✅ Good: Simple, clear templates
api_url: "{{ .env.API_BASE_URL }}/v1"
timeout: "{{ .config.timeout | default 30 }}"
enabled: "{{ .env.FEATURE_ENABLED | default 'false' | bool }}"

# ❌ Avoid: Complex template logic
complex_value: "{{ if and (gt .count 0) (lt .count 100) (eq .type 'premium') }}high{{ else if and (gt .count 0) (eq .type 'basic') }}medium{{ else }}low{{ end }}"

Common Patterns

Environment Configuration

Environment variables are frequently used for configuration:

# Database configuration
database:
  host: "{{ .env.DB_HOST | default 'localhost' }}"
  port: "{{ .env.DB_PORT | default '5432' | int }}"
  ssl: "{{ .env.DB_SSL | default 'false' | bool }}"

# API configuration
api:
  base_url: "{{ .env.API_BASE_URL }}"
  timeout: "{{ .env.API_TIMEOUT | default '30' | int }}"
  retries: "{{ .env.API_RETRIES | default '3' | int }}"

Reference Patterns

Use $ref and $use for reusable components:

# Reference to shared schema
input:
  $ref: "schemas/user-input.yaml"

# Use shared tool
tool:
  $use: "tools/data-validator.yaml"

# Reference with filters
schema:
  $ref: "local::schemas.#(id=='user_schema')"

References

Template Functions

Learn about built-in template functions for data transformation

Context Variables

Understand available context variables in templates