Why Single-Line JSON Is Perfect for Environment Variables
Storing JSON configuration in environment variables is common in containerized and cloud-native applications. Single-line JSON is essential for this pattern to work correctly.
Why Environment Variables Cannot Contain Newlines
Environment variables are defined as name=value pairs in shell syntax. The value is everything after the = sign until a newline. Multi-line values require explicit quoting and escaping that varies between shells, CI systems, and container runtimes. Single-line values work reliably everywhere without any shell quoting complexity.
In Docker, Kubernetes ConfigMaps and Secrets, GitHub Actions, and most CI/CD platforms, environment variables are single-line string values. Attempting to store a multi-line formatted JSON as an environment variable typically either fails to parse or silently truncates at the first newline.
Converting Configuration JSON to a Single Line
Before storing a JSON configuration in an environment variable, convert it to a single line: jq -c . config.json > /dev/null && jq -c . config.json or python3 -c "import sys,json; print(json.dumps(json.load(open(sys.argv[1]))))" config.json. Both commands produce a validated, compact single-line JSON string.
Some teams store the multi-line version in a JSON file for readability and generate the environment variable at deploy time. The CI/CD pipeline reads the file, compacts it, and injects it as an environment variable. This separates the human-readable source from the machine-optimized deployed value.
Reading JSON from Environment Variables in Code
In Node.js: const config = JSON.parse(process.env.MY_CONFIG); reads the environment variable and parses it. Wrap in try/catch to handle missing or invalid values. In Python: import json, os; config = json.loads(os.environ["MY_CONFIG"]).
Always validate the parsed configuration against a schema immediately after parsing. Environment variables can be misconfigured, missing, or corrupted. Schema validation at startup catches these issues with clear error messages before they cause cryptic failures in application logic.
Security Considerations
Environment variables are visible to all processes running as the same user and can appear in process listings, logs, and crash reports. Avoid storing secrets (API keys, passwords, database credentials) directly as JSON in environment variables. Use a secrets management system (AWS Secrets Manager, HashiCorp Vault, Kubernetes Secrets) instead.
If you must store sensitive JSON in environment variables, ensure the variable is not logged. Audit your logging code to confirm that environment dumps, startup logs, and error reports do not include the raw variable value.
Try JSON to One Line Free Online
No sign-up required. 100% client-side — your data never leaves your browser.
Open JSON to One Linearrow_forwardFrequently Asked Questions
How do I set a JSON environment variable in Docker?
In a Dockerfile: ENV MY_CONFIG={"host":"db","port":5432}. In docker run: docker run -e MY_CONFIG='{...}' myimage. In docker-compose: use the env_file option to read from a .env file where the value is the single-line JSON.
Can Kubernetes store multi-line JSON in a ConfigMap?
Yes, ConfigMaps support multi-line values when mounted as files. However, when injecting as environment variables, the value must be a single line. Use single-line JSON for env vars; use file mounts for multi-line JSON.
How do I handle JSON with quotes in a shell environment variable?
Use single quotes to wrap the value in the shell: export MY_CONFIG='{"key":"value"}'. Single quotes prevent the shell from interpreting the double quotes. In .env files, wrap in double quotes and escape internal quotes.