Developer Guide
JSON for Configuration Files
How to structure, validate, and version config.json files. Covers environment overlays, JSON Schema, comments versus JSONC, and keeping secrets out of git.
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.
Unlike an API body, a config file is edited by humans, reviewed in git, and loaded once at process start. The cost of a typo is a failed boot, not a single 400. That is why a schema and an example file matter as much as the shape itself.
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.
If a section grows past a page, split it and merge at startup. Fold nested keys in /tools/json-editor; confirm line and column in /tools/json-formatter when CI says the file is invalid.
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".
Give every URL a scheme. Give every port a number, not "3000". Feature flags should be booleans or enums, not comments someone uncomments to enable a path.
Environment overlays
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. Deep-merge objects; replace arrays. Document the merge order in one paragraph so nobody guesses.
Inject PORT and DATABASE_URL from the environment after you load the file. List overridable keys; do not invent a second undocumented channel.
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.
/tools/json-formatter and /tools/json-editor catch syntax errors; a schema catches semantic ones, like a missing database.host. Ace on the editor will not apply your schema — it only JSON.parses. Status shows valid or invalid with the engine message, without line and column.
Comments, JSONC, 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. Trailing commas fail the same way. Format in /tools/json-formatter before you commit if the file must be RFC 8259 JSON.
Secrets do not belong in git
API keys, database passwords, and JWT signing secrets should come from the environment, a secret manager, or a gitignored overlay. History remembers files you “removed” two commits later. Put placeholders in config.example.json ("password": "set-via-DATABASE_URL") so the shape is obvious without the value.
If a secret is already committed, rotate it; deleting the line is not enough.
Common pitfalls
Copying production config.json into a ticket leaks credentials. JSONC comments break Node JSON.parse and require. Storing "port": "3000" as a string invites concatenation bugs.
Ace fold on /tools/json-editor is not the data tree on /tools/json-formatter.
- Commit an example file, not the secrets.
- Validate syntax and schema in CI.
- Tree view and line+column errors are on
/tools/json-formatter.
Worked examples
Worked config.json
{
"app": {
"name": "billing-worker",
"logLevel": "info"
},
"server": {
"host": "0.0.0.0",
"port": 3000
},
"database": {
"host": "localhost",
"port": 5432,
"name": "billing",
"ssl": false
},
"features": {
"exportCsv": true
}
}This is an example overlay, not production. Put passwords in the environment. Open it in /tools/json-editor to fold database, then validate in /tools/json-formatter.
Invalid comment in strict JSON
{
// do not use in production
"port": 3000
}JSON.parse throws — comments are not legal JSON.JSONC loaders accept this. Node JSON.parse and the formatter do not. Keep comments in JSONC files your tooling actually parses as JSONC.
Frequently asked questions
Should I use YAML instead?
YAML is nicer for comments and multiline strings, and easier to mis-indent. JSON is stricter and maps cleanly to objects. Pick one per project; do not convert back and forth in the hot path.
How do I keep environment differences small?
Commit a default file, overlay one gitignored file per environment, and allow a short list of environment variables to win last.
Can I put a JWT secret in config.json?
Not in a committed file. Inject it at boot. The example file should show the key name with a dummy value.
Which tool should I use to edit config.json?
/tools/json-editor for Ace, format, minify, and fold. /tools/json-formatter for tree view, key sorting, line-column errors, and a .json download.
Summary
A good config.json is small, validated, and free of secrets. Edit it in /tools/json-editor, confirm syntax in /tools/json-formatter, keep a schema in CI, and overlay environment values instead of committing them.