---
title: "YAML (index.yaml)"
description: "Page metadata, indentation-clean."
canonical: "https://geordy.ai/formats/yaml"
---
# YAML

**Page metadata, indentation-clean.**

Configuration-style metadata: title, summary, canonical, taxonomy, last-updated. Easy for tooling to ingest, easier still for retrieval pipelines to filter.

YAML (YAML Ain't Markup Language) is a human-readable data serialization format designed for configuration files and data exchange between systems with different data structures. Created in 2001 to provide a more human-friendly alternative to XML for configuration and data serialization.

## At a glance

- File: `index.yaml`
- First released: 2001
- Created by: Clark Evans, Ingy döt Net, Oren Ben-Kiki
- Specification: https://yaml.org/spec/1.2.2/
- Read by: ChatGPT, Claude, Perplexity, Build tools, RAG pipelines

## Why it matters for AI

YAML is the lingua franca of configuration in the AI/ML stack - model cards, prompt templates, agent definitions, OpenAPI specs, GitHub Actions, and Kubernetes all use it. LLMs generate and read it fluently, so publishing config and metadata in valid YAML lets agents and AI engines manipulate your system without an HTML scraper.

## Example

```
# AI Optimization Configuration
site:
  name: "Geordy AI Platform"
  domain: "geordy.ai"
  category: "GEO / LLMO"

ai_targeting:
  primary_systems:
    - ChatGPT
    - Claude
    - Perplexity
```

## Benefits

- Human-readable syntax with minimal punctuation
- Widely supported across programming languages and platforms
- Eliminates bracket clutter through indentation-based structure

## Limitations

- Indentation-sensitive (error-prone)
- Slower parsing than JSON
- Security concerns with unsafe loading

## Best practices

- Always use 2-space indentation, never tabs - tabs are explicitly forbidden by the spec for indentation.
- Quote strings that look like booleans, numbers, or dates (`"yes"`, `"01:23"`, `"2026-05-12"`) to avoid implicit type coercion (the famous Norway problem: `NO` -> false).
- Use block style (`key:` newline + indent) for anything human-edited; reserve flow style (`{a: 1}`) for short inline values.
- Validate against a JSON Schema where possible (e.g. `yaml-language-server: $schema=...`) so editors and CI catch errors early.

## Pitfalls

- Trusting `yaml.load()` in PyYAML on untrusted input - it can execute arbitrary Python; always use `yaml.safe_load()`.
- Unquoted version strings like `1.10` parsed as the float `1.1`, silently breaking downstream tooling.
- Mixed indentation across a single block (3 spaces here, 4 there) - most parsers fail with cryptic errors far from the actual line.

## Use cases

- **Human-editable configuration files**
- **Documentation frontmatter**
- **When readability is prioritized**

## Adopters

- Kubernetes (https://kubernetes.io/docs/concepts/overview/working-with-objects/)
- GitHub Actions (https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions)
- Docker Compose (https://docs.docker.com/compose/compose-file/)
- OpenAPI / Swagger (https://swagger.io/specification/)
- Ansible (https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_intro.html)
---

Source: https://geordy.ai/formats/yaml
This is a machine-readable markdown version of that page, generated by Geordy.