What a JSON file is, what to open it with, and how to edit it

Bottom line: before opening a JSON file, confirm its encoding and BOM, then check that the structure is only an object or an array; after editing, always validate it with a parser rather than eyeballing brackets and commas.

It is simply a plain-text file with a .json extension, and even Notepad can open it. The real headache is not "it will not open", but that once it is open you cannot see what you broke.

1. What is actually inside a JSON file

A valid JSON file can contain only one of two things: an object {...} or an array [...]. Nothing else is allowed — no variable declarations, no comments, no functions.

复制{
  "name": "order service",
  "port": 8080,
  "debug": false,
  "upstream": ["10.0.0.11", "10.0.0.12"],
  "timeout": null
}

Recognizing three things structurally is enough:

The file extension does not determine the content: package.json, tsconfig.json, and composer.json are all the same kind of thing; different tools have simply agreed to read different keys from them.

2. Three ways to open it, chosen by scenario

Just a quick look: open it in a browser. Drag the file into a Chrome or Edge window and the browser displays it as-is; if a JSON Viewer extension is installed, it is pretty-printed and made collapsible automatically.

Need to edit the content: use an editor. VS Code, Sublime, and Notepad++ all ship JSON syntax highlighting and bracket matching, and Shift + Alt + F in VS Code formats the document. Note that Windows Notepad may add a BOM when saving, so your configuration changes may not take effect; better to avoid it.

Do not want to install anything, just want to validate: use the online JSON formatter. Paste the content in and you immediately see line and column numbers, error locations, and a collapsible tree; copy the result out when you are done. Data is processed locally in the browser and is not uploaded to a server.

Large files (tens of MB or more): do not force them open in an editor. Opening a 100 MB JSON file in VS Code will stall until you question your life choices; use the command line to inspect the structure first:

复制# Look at the first 20 lines to confirm whether it is an array
head -n 20 data.json

# Use jq to list top-level keys without loading the whole file
jq -r 'keys[]' data.json | head

# Count the array length
jq 'length' data.json

3. What to do when double-clicking opens garbled text

Three causes, each handled differently:

1. It is actually a binary file (for example a compressed archive, or an exported database file, with a .json extension). Use file data.json to see the real type; do not force it to be treated as text.
2. The encoding is not UTF-8. Chinese text encoded as GBK is garbled in a UTF-8 environment. Use the editor's "Reopen with encoding" to try GBK once; if it displays correctly, save it as UTF-8.
3. The file has been encrypted or compressed. The symptom is PK (zip) or a pile of question marks at the beginning; these files have to be decompressed or decrypted first.

4. How to confirm nothing broke after editing

JSON has zero tolerance: one missing comma, one extra comma, or one missing quote and the whole file is dead, and the reported error location often points at the next line. So you must validate after editing; do not rely on your eyes.

The three high-risk editing actions, ordered by how often they cause trouble:

Validation is simple: paste it into the online validator and look for red text, or run one line on the command line:

复制python3 -m json.tool config.json > /dev/null && echo OK

If it prints OK, the file is valid. If you want to validate field types as well (for example port must be a number and name must not be empty), writing a JSON Schema is far more reliable than human eyes.

5. How .json differs from its close relatives

Do not be surprised to see comments in tsconfig.json; it is actually handled as .jsonc. Feed the same content to JSON.parse and it will raise an error. When you need to convert between them, use JSON5 to JSON to strip comments and trailing commas in one click.

6. When it is time to switch storage formats

JSON suits scenarios where "the structure is not fixed, humans need to read it, and it travels across languages". If a file exceeds tens of MB, the field structure is stable, and you need conditional queries, staying on JSON is just making trouble for yourself — move to SQLite, Parquet, or load it into a database; read/write performance differs by orders of magnitude. For the specific trade-offs, see Parsing and streaming large JSON.

FAQ

How can I inspect a JSON file too large to open?

Do not force it open in an editor; opening a 100 MB JSON file in VS Code will stall until you question your life choices. Use the command line to inspect the structure first: head -n 20 confirms whether it is an array, jq -r 'keys[]' lists only top-level keys, and jq 'length' counts the array length. None of these commands loads the whole file.

Why do my edits in Notepad stop the configuration from taking effect?

Windows Notepad may add a BOM when saving, and a file with a BOM fails configuration parsing, so the edited content never takes effect. The article's recommendation is to use editors such as VS Code, Sublime, or Notepad++, which ship JSON syntax highlighting and bracket matching. If you already used Notepad, save again as "UTF-8 without BOM" and retry.

Can I treat a JSON file as JSON5 and add comments?

No — a standard parser does not allow comments in a .json file and JSON.parse raises an error immediately. Comments belong in .jsonc or .json5 files read by the matching parser. Files such as tsconfig.json are actually handled as .jsonc; feed the same content to JSON.parse and it fails.