Flattening Nested YAML Keys to ENV Variables

Nested YAML structures are extremely common in application configuration, but ENV files are strictly flat. The conversion requires a flattening strategy that preserves the hierarchical information in the variable name.

A nested YAML configuration:

server:
  http:
    host: 0.0.0.0
    port: 3000
  https:
    enabled: true
    port: 443
    cert: /etc/ssl/cert.pem
database:
  primary:
    host: db-master.example.com
    port: 5432
    name: myapp
  replica:
    host: db-replica.example.com
    port: 5432

Flattened with single underscore separator:

SERVER_HTTP_HOST=0.0.0.0
SERVER_HTTP_PORT=3000
SERVER_HTTPS_ENABLED=true
SERVER_HTTPS_PORT=443
SERVER_HTTPS_CERT=/etc/ssl/cert.pem
DATABASE_PRIMARY_HOST=db-master.example.com
DATABASE_PRIMARY_PORT=5432
DATABASE_PRIMARY_NAME=myapp
DATABASE_REPLICA_HOST=db-replica.example.com
DATABASE_REPLICA_PORT=5432

Flattened with double underscore separator:

SERVER__HTTP__HOST=0.0.0.0
SERVER__HTTP__PORT=3000
SERVER__HTTPS__ENABLED=true

Separator conventions:

1. Single underscore (_) -- Most common. Simple and readable, but ambiguous when the original key itself contains underscores (e.g., pool_size under database becomes DATABASE_POOL_SIZE, indistinguishable from a three-level nesting).
2. Double underscore (__) -- Used by ASP.NET Core, Django, and some other frameworks. Eliminates ambiguity: DATABASE__POOL_SIZE clearly has two levels with a key containing an underscore.
3. Dot separator (.) -- Used by Spring Boot (server.http.port=3000). Not a valid character in shell environment variable names, so it only works with framework-specific parsers.

Handling arrays in nested YAML:

allowed_origins:
  - https://example.com
  - https://app.example.com

Can be flattened as:

ALLOWED_ORIGINS_0=https://example.com
ALLOWED_ORIGINS_1=https://app.example.com
# or as a comma-separated list:
ALLOWED_ORIGINS=https://example.com,https://app.example.com

The choice of separator and array handling depends on the framework or tool that will consume the ENV variables. Always check the documentation of your target platform.