Working with JSON
The format is small enough to learn in an afternoon and subtle enough to lose data in production. These are the parts that catch people out.
JSON earns its place by being tiny. The entire grammar fits on a single page — json.org draws it as six railroad diagrams, and RFC 8259 is a twenty-minute read, and ECMA-404 says the same thing again in fewer pages still. That is the whole appeal: any two systems can agree on it without a meeting.
The trouble starts with what the grammar leaves out. There are no comments, so configuration written in JSON has nowhere to explain itself. There is no date type, so every team invents one. And numbers are specified as decimal literals with no stated limit, which sounds generous until you notice that JSON.parse hands you a double. Anything past Number.MAX_SAFE_INTEGER comes back rounded, silently — no exception, no warning, just a different number than the one that was sent. If your identifiers are 19 digits long, and SIM and account numbers usually are, that is a live bug.
The second thing that catches people is that the syntax is unforgiving in a way its size does not prepare you for. A trailing comma after the last element is legal in JavaScript source and illegal in JSON, which is why so much hand-edited configuration fails to load. Single quotes are not string delimiters. Neither is a bare word. The parser is right and the file is wrong, and the error message rarely says so in those terms — it names a character offset and leaves you to count.
The articles below take those one at a time, with the actual payload and the actual error text rather than a description of it. If you have a file in front of you right now, JSON to Table will show you its shape faster than reading it will.
JSON articles
JSON vs NDJSON: what happens when the file gets big
A JSON array and an NDJSON file hold the same records. They behave completely differently the moment the file outgrows your memory, the process dies halfway, or one line is corrupt.
Read the guideYour JSON parser is rounding your IDs and not telling you
A user reported that our own tool was changing his SIM card numbers. He was right. Here is the bug, why every JavaScript parser has it, and the fix — which is not the one most people reach for.
Read the guideHow to open a JSON file (and why double-clicking does nothing)
You downloaded a .json file, double-clicked it, and either nothing happened or Notepad showed you one endless line. Here is what is actually going on and how to read it properly on Windows, Mac, and Linux.
Read the guideJSON vs XML: which one I actually reach for, and why
Not a spec comparison. The three questions I ask when choosing between them, why XML is not dead, and the one JSON limitation that catches people out in production.
Read the guide