JSON and YAML Guide for AI Agents: Config File Mastery

Why Configuration Formats Matter

Configuration files control how software behaves. As an agent, you'll:

• Read configs to understand settings


• Edit configs to change behavior


• Create configs for new setups

JSON and YAML are the most common formats.

JSON Basics

Structure

JSON uses:

• Objects: {}


• Arrays: []


• Strings: "text"


• Numbers: 42, 3.14


• Booleans: true, false


• Null: null

Example

{
  "name": "MyAgent",
  "version": "1.0.0",
  "enabled": true,
  "maxRetries": 3,
  "tags": ["production", "critical"],
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "mydb"
  },
  "features": null
}

Rules

• Keys must be strings in double quotes
• Strings must use double quotes
• No trailing commas
• No comments (standard JSON)

Common Mistakes

// WRONG - comments not allowed
{
  name: "Test",           // Keys need quotes
  "description": 'text',  // Single quotes not allowed
  "items": [1, 2, 3,],    // Trailing comma not allowed
}

// CORRECT
{
  "name": "Test",
  "description": "text",
  "items": [1, 2, 3]
}

YAML Basics

Structure

YAML uses indentation for nesting:

name: MyAgent
version: "1.0.0"
enabled: true
maxRetries: 3
tags:
  - production
  - critical
database:
  host: localhost
  port: 5432
  name: mydb
features: null

Rules

• Indentation matters (use spaces, not tabs)
• 2 spaces per level is standard
• Keys don't need quotes (usually)
• Strings often don't need quotes

Quoting in YAML

When to quote strings:

# No quotes needed
simple: hello world
path: /usr/local/bin

# Quotes needed for special characters
colon: "has: colon"
special: "yes"  # 'yes' without quotes = boolean true
number_string: "123"  # Want string, not number

Multi-line Strings

# Literal block (preserves newlines)
description: |
  This is line one.
  This is line two.
  Newlines are preserved.

# Folded block (collapses newlines)
summary: >
  This is all one line
  even though it's written
  on multiple lines.

Anchors and Aliases

Avoid repetition:

defaults: &defaults
  timeout: 30
  retries: 3

production:
  <<: *defaults
  host: prod.example.com

development:
  <<: *defaults
  host: localhost

JSON vs YAML

Aspect

JSON

YAML

Readability	Moderate	High
Verbosity	More	Less
Comments	No	Yes
Data types	Limited	More
Parsing	Fast	Slower
Error-prone	Less	More (indentation)

When to Use JSON

• API responses
• Data interchange
• When strict format needed
• JavaScript/Web environments

When to Use YAML

• Human-edited configs
• When comments needed
• Complex configurations
• Docker, Kubernetes, CI/CD

Common Patterns

Environment-Specific Config

# config.yaml
defaults:
  timeout: 30
  retries: 3

environments:
  development:
    debug: true
    database_url: postgres://localhost/dev
  
  production:
    debug: false
    database_url: ${DATABASE_URL}

Feature Flags

features:
  new_ui: true
  beta_api: false
  experiments:
    - name: dark_mode
      enabled: true
      percentage: 50

Service Configuration

services:
  api:
    port: 8080
    host: 0.0.0.0
    cors:
      origins:
        - https://example.com
      methods:
        - GET
        - POST
  
  worker:
    concurrency: 4
    queue: default

Working with Configs

Reading JSON

# Using jq
cat config.json | jq '.database.host'

# Parse in code
import json
with open('config.json') as f:
    config = json.load(f)

Reading YAML

# Using yq
cat config.yaml | yq '.database.host'

# Parse in code
import yaml
with open('config.yaml') as f:
    config = yaml.safe_load(f)

Editing Configs

For small changes, use targeted edits:

# Edit specific key in JSON
edit(
    path="config.json",
    oldText='"debug": false',
    newText='"debug": true'
)

Converting

# YAML to JSON
yq -o json config.yaml > config.json

# JSON to YAML  
yq -P config.json > config.yaml

Validation

JSON Schema

Define expected structure:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["name", "version"],
  "properties": {
    "name": {"type": "string"},
    "version": {"type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$"}
  }
}

YAML Linting

yamllint config.yaml

Debugging Config Issues

JSON Parse Errors

Error: Unexpected token at position 42

Common causes:

• Trailing comma


• Missing quote


• Single quotes instead of double


• Unescaped special characters

YAML Parse Errors

Error: bad indentation at line 15

Common causes:

• Mixed tabs and spaces


• Inconsistent indentation


• Missing colon


• Unquoted special values

Debugging Steps

Use a linter/validator

Check line mentioned in error

Look for the common mistakes above

Try simpler version first

Best Practices

Use Environment Variables

database:
  url: ${DATABASE_URL}
  password: ${DB_PASSWORD}

Comment Complex Settings

# Rate limit for API calls
# Increase for high-traffic deployments
rate_limit: 100  # requests per second

Version Your Configs

config_version: 2
# Schema changed in v2: 'port' moved under 'server'

Keep Defaults Sensible

timeout: 30      # Sensible default
retries: 3       # Not 0 or 100
debug: false     # Safe default

Conclusion

JSON and YAML are fundamental to agent work. Know their syntax, understand their trade-offs, and handle them carefully—a misplaced comma can break deployments.

---

Next: Environment Variables Guide - Managing configuration through environment