Developer Guide
JSON for Configuration Files
How to structure, validate, and version config.json files. Covers environment splits, JSON Schema, comments, and secrets — plus a working example.
JSON is the default configuration format for Node.js (package.json, tsconfig.json), many CLIs, editor settings, and infrastructure tools. It is easy to parse in every language, but it has no comments, no trailing commas, and it is a poor place to store secrets. This guide covers how to structure a config.json file so it stays readable, valid, and safe to commit.
Why teams use config.json
A JSON config file is a contract: the same object can be read by a Node script, a Python worker, and a CI job. Unlike YAML it has one data model and fewer implicit types. Unlike .env files it supports nested objects and arrays. The cost is strict syntax — one missing comma breaks the whole file — so you should validate the file in CI, not only at runtime.
A practical config.json shape
Group settings by concern, not by the first feature that needed them. A typical root object has app, server, database, and features keys. Use consistent naming (all camelCase or all snake_case). Prefer explicit booleans and numbers over stringly-typed flags like "true". Keep the file small enough to review in a pull request; if a section grows past a page, split it into a second file and merge at startup.
Environment-specific configs
Commit a config.example.json (or config.default.json) with safe dummy values. Load config.local.json or config.production.json on top of the default, and gitignore the environment-specific files. For secrets — API keys, database passwords, JWT signing keys — use environment variables and interpolate them when the app boots. Never put production credentials in a file that history can leak.
Validate with JSON Schema
JSON Schema turns "we hope the config is right" into a checkable contract. Define required keys, types, and allowed enums (for example logLevel: debug | info | error). Run the schema in CI and at process start so a typo in a port number fails fast. Our JSON Formatter and JSON Editor catch syntax errors; a schema catches semantic ones, like a missing database.host.
Comments and trailing commas
Standard JSON rejects comments and trailing commas, which is why tsconfig.json and many editor configs are actually JSONC. If you need comments, pick one convention: JSONC for developer tooling, or a "_comment" string field that your loader ignores. Do not mix both. When you paste a config into a strict parser (most production runtimes), strip comments first or the load will fail.
Version control checklist
Commit the example file, the schema, and a one-page README of every key. Gitignore local overrides and anything with secrets. In code review, treat a config change like an API change: say what default changed and who is affected. After merge, validate the file in the pipeline before you deploy.
Summary
A good config.json is small, validated, and free of secrets. Use the JSON Editor to inspect and fix the file, then keep a schema in CI so the next typo never reaches production.