Chapter 4: Understanding YAML

The Problem

AI generated a file. It looks like code. There are colons, dashes, and indentation. You're not sure what any of it means, and you're definitely not sure if it's correct.

This chapter teaches you to read YAML—not to write it from scratch, but to understand what AI produces so you can verify it makes sense.

The Key Idea

Core concept

YAML is a way to write structured information in plain text. It's like a form, but as a text file.

Where a web form has fields and values, YAML has keys and values. Where a form has sections, YAML has indentation. That's really all there is to it.

The Basics: Keys and Values

Every piece of information in YAML is a key-value pair:

name: High-Value Customers

• name is the key (what kind of information)
• High-Value Customers is the value (the actual information)
• The colon (:) separates them

Think of it like a label and its contents:

• Label: Name
• Contents: High-Value Customers

Lists: Multiple Items

When you have multiple items, use dashes:

colors:
  - red
  - green
  - blue

This says "colors" contains three items: red, green, and blue.

In marketing terms, this might be:

target_regions:
  - North America
  - Europe
  - Asia Pacific

Nesting: Information Inside Information

Indentation shows that something belongs inside something else:

segment:
  name: High-Value Customers
  description: Customers with lifetime value over $1000

Here, name and description are inside segment. They're properties of the segment, not standalone values.

The indentation (two spaces) is what creates this relationship. Everything indented under segment: belongs to it.

A Real Example

Here's a segment definition you might see AI generate:

name: High-Value Customers
description: Customers with lifetime value over $1000
rules:
  - attribute: lifetime_value
    operator: Greater
    value: 1000

Let's read it piece by piece:

Line	What It Means
name: High-Value Customers	This segment is called "High-Value Customers"
description: ...	A human-readable explanation
rules:	Here come the targeting rules
- attribute: lifetime_value	First rule: look at the lifetime_value field
operator: Greater	Check if it's greater than...
value: 1000	...1000

Mental Model: Forms and Folders

Think of YAML like a paper form combined with a folder system:

• Key-value pairs are form fields (Name: _______)
• Lists are numbered items (1. ___ 2. ___ 3. ___)
• Nesting is putting forms inside folders

When you see:

activations:
  - connection: salesforce
    enabled: true
  - connection: google-ads
    enabled: false

You're looking at an "activations" folder containing two forms:

1. Salesforce activation (enabled)
2. Google Ads activation (disabled)

Reading Tips

Follow the indentation. Items at the same indentation level are siblings. Items indented further are children.

Dashes mean "one of many." When you see -, you're looking at an item in a list. There might be more items below it.

Colons mean "here's the value." Whatever comes after : is the actual data.

Quotes are optional for simple text. name: Hello and name: "Hello" mean the same thing. AI might use quotes for text with special characters.

What AI Generates vs. What You Review

AI handles:

• Correct indentation
• Proper syntax
• Required fields

You verify:

• Does the name make sense?
• Are the rules targeting who I want?
• Are the values correct?

You're not checking for typos in the syntax. You're checking that the meaning matches your intent.

Common Patterns You'll See

A segment:

name: [segment name]
description: [what it targets]
rules:
  - attribute: [field name]
    operator: [comparison type]
    value: [target value]

An activation:

activations:
  - connection: [destination name]
    enabled: true
    schedule:
      frequency: daily

A journey:

name: [journey name]
stages:
  - name: [stage name]
    steps:
      - type: [step type]
        name: [step name]

Pitfalls

"The indentation looks wrong."

YAML is strict about indentation. If something looks misaligned, it might actually be an error. Ask AI: "Is the indentation correct in this file?"

"I don't know what an operator means."

You don't need to memorize operators. Ask AI: "What does the 'Greater' operator do?" or "What operators can I use for date fields?"

"There are fields I don't recognize."

YAML files can have many optional fields. Focus on the ones that matter: name, rules, activations. Ask AI about unfamiliar fields.

What You've Learned

• YAML is structured text with keys, values, lists, and nesting
• Indentation shows what belongs inside what
• Dashes indicate list items
• Your job is to verify meaning, not syntax
• When confused, ask AI to explain

Next Step

Now you can read the format. Chapter 5 explains what the data inside these files represents—where customer information comes from and how it's organized.

---

You can read the language. Next, you'll understand what it's describing.