YAML Flattener.

What is YAML flattening?

Flattening converts a nested YAML object into a flat map of dot-separated keys. For example, database.primary.host: db.internal becomes a single key with a single value instead of three levels of nesting. This is useful for environment variable mapping, feature flag configuration, and flat-file key-value stores.

The reverse operation — unflattening — takes a flat map of dotted keys and reconstructs the nested YAML structure. So database.primary.host: db.internal becomes database: primary: host: db.internal. Both operations preserve values exactly; only the key structure changes.

When to flatten YAML.

Environment variables. Many systems (Docker, Kubernetes, CI/CD) use environment variables like DATABASE_PRIMARY_HOST=db.internal to set config. Flattening a YAML config makes it easy to map every value to an env var by joining the key path with underscores.

Feature flags. Feature flag systems often require flat key-value pairs. Flattening a nested YAML config gives you the dotted keys that flag systems expect, without manually writing out every path.

Configuration layering. When combining multiple config sources (defaults + overrides + env vars), a flat structure makes it easy to merge and compare. Flatten all sources, apply overrides, then unflatten back to YAML.

How the conversion works.

The flatten function recursively walks the YAML object. For each leaf value (string, number, boolean, null), it builds the full key path by joining parent keys with dots. Arrays are flattened with numeric indices: items.0.name. The result is a single-level object where every key is the full path to a value.

The unflatten function reverses this: it splits each key on dots, creates nested objects along the path, and assigns the value at the deepest level. Numeric indices are converted back to array elements when possible.

Dotted keys and naming conventions.

When flattening, the separator between key levels is a dot by default. The flattened key database.primary.host represents the path from the root object through database, then primary, then host. Different tools and platforms use different separators — Kubernetes uses underscores in environment variables (DATABASE_PRIMARY_HOST), while some config systems use double colons (database::primary::host). After flattening, you can replace dots with your target separator using search and replace.

Naming conventions matter when mapping flattened keys to environment variables. Most shell environments restrict variable names to letters, digits, and underscores. Dots are not valid in environment variable names, so you must replace them. The standard approach is to convert dots to underscores and uppercase everything: database.primary.host becomes DATABASE_PRIMARY_HOST. This converter gives you the dotted keys; you handle the final transformation in your deployment scripts.

Working with arrays in flattened YAML.

Arrays in YAML become numeric indices in flattened form. A list like fruits: [apple, banana, cherry] flattens to fruits.0: apple, fruits.1: banana, fruits.2: cherry. This is useful for environment variable mapping where each array element gets its own variable: FRUITS_0=apple, FRUITS_1=banana. Many CI/CD systems and Docker Compose support this pattern for passing arrays through environment variables.

Nested arrays flatten recursively. An array of objects becomes a set of indexed paths: users.0.name: Alice, users.0.age: 30, users.1.name: Bob. When unflattening back, numeric keys are automatically converted back to array elements. Be careful with sparse arrays — if you flatten [a, , c] (missing index 1), the unflattened result may not preserve the gap depending on the YAML parser.

Practical flattening workflows.

Docker Compose environment variables. Docker Compose supports environment variables with nested keys: services.api.environment.DATABASE_HOST. Flattening your YAML config gives you the exact variable names Compose expects. Kubernetes ConfigMaps. When creating ConfigMaps from YAML data, flattening makes it easy to map each key to a data entry. Terraform variables. Terraform's TF_VAR_ environment variables use underscores and uppercase for nested values.

Feature flag systems. Services like LaunchDarkly, Flagsmith, and Unleash store flags as flat key-value pairs. Flattening a nested YAML config gives you the dotted keys that these systems expect. Combine flatten with a search-and-replace step to match your flag system's naming convention. The two-way conversion means you can always unflatten back to a nested structure for human editing.