DEV Community

xushoulin
xushoulin

Posted on

I built 13 JSON tools that never touch a server. These are the edge cases that nearly broke them.

If you've ever pasted an API response into a "free online JSON formatter", this is a public service announcement: check where your data goes first. Most of those sites POST your document to their backend before showing you a pretty-printed version.

I kept doing it anyway — until the day the payload contained real customer records. So I spent the last few weeks building DevTinyTools: 13 JSON tools that run entirely in the browser tab. No backend, no uploads, works offline after the first load. This post is about the parts that were harder than they looked, because JSON looks simple and absolutely is not.

1. "Valid JSON" is a smaller category than people think

The validator's job is to translate parser errors into English. That meant collecting what different parsers actually say for the same broken document:

Input V8 (JSON.parse) Python (json)
{a: 1} Unexpected token a ... is not valid JSON Expecting property name enclosed in double quotes
{"a": 1,} Unexpected non-whitespace character after JSON Illegal trailing comma
{'a': 1} Unexpected token ' Expecting property name enclosed in double quotes

Same document, same "invalid" verdict, completely different words. If your error page only knows V8's vocabulary, half your users are left guessing.

2. null vs missing vs undefined — three different things your model must not confuse

The code generators (JSON → TypeScript/Go/Java/C#/Python) all share one type-inference engine, and the entire product lives in this rule:

  • A key present in every sampled array element → required
  • A key present with value null in every element → optional, typed as nullable
  • A key present in some elements → optional, and in Go it gets ,omitempty

Get this wrong and the generated model "works" — until the first response that omits a field, and suddenly your Go struct reports "" where the API said nothing at all. That's the worst kind of bug: the model invents a value for a key the document never sent.

3. The 2^53 problem

JSON.parse reads every number as a float64. IDs above 9,007,199,254,740,991 silently lose precision — Stripe's evt_ payloads and snowflake IDs have both burned people here. The formatter keeps long numbers as raw text (it never re-serializes through a float), and the Python generator even documents the contrast: Python's int is arbitrary precision, so a 19-digit id survives there but not in JavaScript.

4. YAML is not "JSON with less punctuation"

The newest tool converts JSON ↔ YAML, and the typing traps outnumber the syntax differences:

  • YAML 1.1 readers parse yes, no, on, off as booleans. YAML 1.2 — the current spec — treats them as strings. Same file, two libraries, different data.
  • version: 1.20 is the number 1.2 (trailing zero gone). Every version tag in a config file should be quoted.
  • Multiple --- documents in one file have no single-document JSON equivalent; the converter turns a stream into a JSON array instead of dropping documents on the floor.

5. Converting a folder of files without a server

Batch mode needed a downloadable ZIP with zero dependencies — so it writes the ZIP format by hand: local file headers, a table-driven CRC-32, and the end-of-central-directory record. ~130 lines, STORE method (no compression), and honestly the most fun I had on the project.

Try it

Everything above lives at shoulin.shop — open DevTools, paste your biggest payload, watch the network tab stay empty. The guides quote real error messages from V8, CPython, Jackson and encoding/json, so they're useful even if you never use the tools.

If you hit a document that converts wrongly, that's the feedback I want most — drop it in the comments (redacted, obviously).

Top comments (0)