Boolean Values in YAML to ENV Conversion

Boolean values require special attention when converting between YAML and ENV formats. YAML has a rich set of boolean representations, while ENV files treat everything as plain strings. This mismatch can cause subtle bugs if not handled carefully.

YAML booleans (YAML 1.1 recognizes all of these):

feature_enabled: true
debug_mode: false
use_ssl: yes
verbose: no
maintenance: on
notifications: off
strict_mode: True
legacy_support: FALSE

Standard ENV conversion:

FEATURE_ENABLED=true
DEBUG_MODE=false
USE_SSL=true
VERBOSE=false
MAINTENANCE=true
NOTIFICATIONS=false
STRICT_MODE=true
LEGACY_SUPPORT=false

Why this matters:

When YAML is parsed, values like yes, no, on, off, True, FALSE are all interpreted as boolean true or false. A proper YAML-to-ENV converter normalizes all of these to the standard true/false strings.

The problem on the consuming side:

Different languages and frameworks parse ENV boolean strings differently:

// Node.js - no automatic boolean parsing
process.env.DEBUG_MODE          // "false" (string)
process.env.DEBUG_MODE === true // false (correct)
process.env.DEBUG_MODE == true  // false (correct)
Boolean(process.env.DEBUG_MODE) // true! (WRONG - any non-empty string is truthy)

# Python
os.environ["DEBUG_MODE"]             # "false" (string)
bool(os.environ["DEBUG_MODE"])       # True! (WRONG - any non-empty string is truthy)
os.environ["DEBUG_MODE"] == "true"   # False (correct way)

Best practices:

1. Always normalize to true/false when converting YAML to ENV. Never output yes, on, 1, etc.
2. In your application code, explicitly compare against the string "true" rather than using language-native boolean casting.
3. Consider using 1/0 if your framework specifically expects numeric booleans.
4. Document your convention in the project README or .env.example file.

If you need to preserve the original YAML boolean style (e.g., yes vs true), quote the value in YAML: use_ssl: "yes" -- this makes it a string rather than a boolean.