2026-07-02 · Calc-Tools Editor

JSON Formatter: Beautify, Minify, and Validate JSON

JSON is the default choice when machines exchange data, and it is also a format that looks universally applicable while carrying hard edges everywhere. A formatter answers one question — is this text syntactically valid — and leaves three harder ones untouched: will this structure survive a trip through another language unchanged? Can it express the types you actually need? And what should the protocol layer do once the payload grows?

This article deals only with JSON's engineering boundaries: which numbers get silently rewritten during parsing, which fields vanish during serialization, why the same file can produce different results in different languages, and what to do with very large payloads. Every figure below was measured on Node 22 and can be reproduced.

1. When JSON Is the Wrong Answer: Choosing Among Five Formats

Four questions decide a data format: who writes it, who reads it, does it need comments, does it need types. JSON has almost no rival in the "machine writes, machine reads" cell. The moment a human writes the file, or comments and type information matter, it starts to strain.

It compresses into three sentences: data produced by a program and consumed by a program belongs in JSON; configuration that a human writes, that needs comments and stays shallow, belongs in TOML or YAML; flat tables belong in CSV, and XML earns its place only when namespaces and strict schema validation are required. JSON's real advantage is not that it is pleasant to write — it is that it is unambiguous. A parser in any language reads the same text into the same structure, which is exactly why interface layers picked it, and exactly what it gave up comments and types to buy.

2. Numbers: JSON Has Exactly One Numeric Type

RFC 8259 defines only the syntax of a number — optional minus sign, integer part, optional fraction, optional exponent. It says nothing about range or precision; section 6 explicitly lets each implementation set its own limits on the numbers it will accept. So "how large is this JSON number" is not a specification question but an implementation question: the same text handed to parsers in different languages can yield different values.

JavaScript is the most familiar implementation of that latitude. JSON.parse puts every number into an IEEE 754 double. The largest integer a double represents exactly is 2^53 − 1, which is 9007199254740991 (about 9.007 × 10^15, sixteen decimal digits). Past that line, representable values are spaced apart, and a number is silently rounded to the nearest representable value — no error, no warning.

The table below was measured value by value on Node 22:

The 9007199254740993 case has a quieter second half: the damage is not confined to parsing. In JavaScript, 9007199254740993 - 9007199254740992 evaluates to 0, because both literals are already the same double before the subtraction happens. In other words you cannot detect this loss at runtime — you can only block it before the data enters the system.

Money is the second danger zone, but it fails differently. A decimal such as 19.9 has no exact binary form, so JSON.parse returns the double closest to 19.9; that value drifts the moment it takes part in arithmetic. 19.9 × 3 = 59.699999999999996, and 0.1 + 0.2 = 0.30000000000000004. The industry answer is to carry money as an integer in the smallest currency unit: 19.9 yuan becomes 1990 cents, times three gives 5970, divided by 100 gives 59.70 — the whole path stays in integer territory and nothing rounds.

Timestamps, by contrast, sit comfortably inside the boundary. A 13-digit millisecond timestamp (currently around 1.78 × 10^12) has three orders of magnitude of headroom; a 16-digit microsecond timestamp (about 1.78 × 10^15) is still safe and, extrapolating from the measured ceiling, would not overflow until roughly the year 2255. What is genuinely dangerous is never time — it is identifiers that are really encodings but get treated as quantities.

Two hard conventions follow. Identifiers beyond fifteen significant digits — order numbers, snowflake IDs, database primary keys — and all monetary amounts are carried as strings or integers, never as JSON numbers. A bigint column does not make a JSON number safe; the double in the middle makes that decision for you and does not announce it.

3. Three Things JSON Does Not Have, and What to Use Instead

JSON's type system has six entries: string, number, boolean, null, object, array. The other three things real systems constantly need — comments, dates, and the state of "this field does not exist at all" — can only be expressed by convention.

Comments: inside the data or outside it

Standard JSON cannot hold comments, so they have exactly two places to live. The first is an ordinary sibling field, conventionally underscore-prefixed, for example _comment, _note or _schema. The advantage is that the note travels with the data and survives copy-paste; the price is that the field really exists in the payload, so consumers must either ignore it explicitly or start asking whether an extra field counts as a contract change. The second place is outside the data: a separate schema file, interface documentation, or JSONC and JSON5 handled only at build time. The test is simple: will some other system pass this JSON through or store it verbatim? If yes, keep the note outside. As for double-slash comments, they work only inside your own build chain — the instant a standard parser reads the file, those two characters are illegal tokens.

Dates: an ISO 8601 string, with a time zone attached

JSON has no date type, so a date can only be a string. The accepted form is ISO 8601 and it must carry an offset or a Z, for example 2026-09-29T08:30:00Z. In testing, JSON.stringify(new Date()) emits exactly that shape with milliseconds, 2026-09-29T08:30:00.000Z, and parsing it back yields a string, not a date object — conversion responsibility always sits in the application layer.

Two differences are easy to miss. The first is precision: mixing second-level and millisecond-level values produces strange ordering and deduplication results, so a team should standardise on milliseconds. The second is the bare date string: 2026-09-29 is an ordinary string in JSON, but YAML will infer a date type from the same characters, so moving one value between formats can change its type without notice. When you mean a calendar day rather than an instant, define it explicitly as a date string with no time part and write that into the schema.

null versus a missing key: two different meanings

This is the softest spot in most API designs. A key that exists with the value null means "this field was explicitly emptied". A key that is absent means "this field was not mentioned this time". The two are fully distinguishable at the data level — in testing, "nickname" in {"nickname":null} is true while "nickname" in {} is false.

The last row deserves its own paragraph. In JavaScript, when an object property holds undefined, JSON.stringify drops the entire key rather than writing null: JSON.stringify({a: undefined, b: 1}) produces {"b":1}. Put the same value in an array and undefined is written as null instead. One notion of "empty" vanishes inside objects, turns into null inside arrays, and at the top level serializing undefined produces no string at all. Downstream, "the field was never sent" and "the field was sent as undefined" are indistinguishable, and only an explicit null can separate them.

Write null and omission into the contract instead of leaving callers to guess. Update endpoints in particular must state whether null clears or deletes a field, and whether omission leaves the value alone or resets it to a default.

4. The Silent-Rewrite Checklist

Beyond numeric precision, serialization performs a set of moves that preserve meaning while changing text. Each one is reasonable on its own; together they make up the hardest part of production debugging, because the data looks "fine" on both sides and still differs.

The BOM row is the one worth memorising. It is the most common cause of "the file is obviously fine but parsing fails", and a BOM is the hardest kind of character to see: it is indistinguishable from the start of an empty file. When a parse failure makes no sense, inspect the head of the text for invisible characters first — running it through a text cleaner and then formatting it again usually resolves the case.

5. Three Reproducible Worked Examples

Example one: how an order number changes on its way from the database to the browser. An orders table uses a 19-digit snowflake primary key, 1234567890123456789. The API returns it as a JSON number. After the browser parses the response the value is 1234567890123456800, with the last two digits rewritten. The user opens the order detail, the front end requests it by that ID, the server finds nothing and returns 404 — and if the lookup ever falls back to nearest-match behaviour, it can return somebody else's order. Use 9876543210987654321 instead and the damage is larger still: the last four digits become 5000. There is exactly one fix: IDs are always strings in JSON, converted explicitly during serialization rather than left to default behaviour.

Example two: why a money total comes out one cent short. A product costs 19.9 yuan and the customer buys three. If the JSON carries the number 19.9, parsing and multiplying yields 59.699999999999996; add rounding, accumulation and a percentage discount and the error compounds until reconciliation shows a difference of one to several cents. Switch to integer cents: unit price 1990, quantity 3, subtotal 5970, discounts computed on integers, and a single division by 100 at the very end. Nothing floats, so nothing drifts. The same reasoning applies to tax allocation and to splitting a coupon proportionally across line items.

Example three: how much minifying actually saves. Take an order object with twelve line items — product names, quantities, unit prices, tags and shipping details — serialize it both ways, and gzip each result:

The conclusion is mildly counter-intuitive: on an uncompressed channel, stripping whitespace saves 44.3%; on a channel that already runs gzip, the same operation saves only another 13.1% — 397 bytes against 345 bytes, a gap of 52 bytes. gzip has already absorbed those highly regular spaces and repeated key names. Repeat the test on a 5000-row array: 200281 bytes minified, 24565 bytes after gzip, a mere 12.3%. So "we have to minify JSON to save bandwidth" is a weak argument on modern transport. What is actually worth optimising is post-parse memory footprint and object count, not the raw byte count.

6. How to Read a Large JSON Document

Quantify "large" first, or the discussion is meaningless. The 5000-row array above is 200281 bytes, roughly 196 KB, which no parser considers large; the real threshold sits in the tens of megabytes to gigabytes. At that scale, parsing everything in one call holds both the source text and the resulting object tree in memory at once, peaks well above the raw byte count, and cannot be undone halfway.

Two measured facts help set priorities. First, nesting depth is usually not the bottleneck: on Node 22 an array nested 10000 levels deep still parses normally, so volume fails long before depth does. Second, chunking beats compression, because gzip shrinks transmitted bytes but not the number of objects you must hold afterwards. Where records are processed one at a time, store the data as NDJSON and use a text diff tool to compare two exports — far more reliable than reading a whole file by eye.

7. Six Conventions Worth Freezing in an API Contract

• Pick one field-naming style and write it down. camelCase and snake_case are equally defensible; mixing them is the disaster, because a consumer then has to remember two spellings for every field. When crossing language boundaries, a case converter can normalise a whole codebase at once.
• IDs are always strings. See example one. There are no exceptions.
• Money is always an integer in the smallest unit, with an explicit currency. {"amount":5970,"currency":"CNY"} is far safer than {"amount":59.7}.
• Dates are always ISO 8601 strings, standardised to milliseconds. Do not mix second-level and millisecond-level values.
• Error objects have a fixed shape. Keep one stable machine-readable field, such as an error code, and put human-readable prose somewhere separate; never make callers match on message text.
• Binary data does not go inside JSON. Base64 inflates a payload by roughly a third, so large files belong on a dedicated binary channel. The trade-offs are covered in the Base64 encoding guide and the Base64 encoder.

Two smaller conventions are worth adding. URL paths conventionally use hyphens while JSON keys use camelCase or underscores; do not let one style leak into the other, and always percent-encode reserved characters in URLs as described in the URL encoder. For field-level format validation — phone numbers, reference codes, time formats — prove the pattern in a regex tester before committing it to the server.

8. Frequently Asked Questions

Why do numbers inside JSON change by themselves?

Because the specification defines only the syntax of a number, not its precision, while mainstream implementations — most notably JavaScript's JSON.parse — carry every number as an IEEE 754 double. The safe integer ceiling is 9007199254740991, and beyond it values round silently: 9007199254740993 becomes 9007199254740992, and a 19-digit snowflake ID comes back with trailing zeros. Carry such values as strings.

What is the actual difference between null and a missing field?

A key present with the value null means "explicitly emptied"; an absent key means "not mentioned this time". The two are fully distinguishable, so a contract has to define each separately. Update endpoints especially must say whether null clears or deletes the field, and whether omission leaves it alone or applies a default.

How should a JSON file of tens of megabytes be read?

Change the shape of the data before changing the parser. Converting the document to NDJSON, one object per line, lets you parse line by line and keep memory independent of file size; if the document must stay whole and you need only a few fields, use event-driven streaming. Parsing everything at once is only reasonable in the tens of KB to a few MB range.

The file looks completely normal, so why does parsing still fail?

Most often because the file begins with a UTF-8 BOM. A BOM is invisible to the eye but is a real character sitting in front of the first brace or bracket, and the parser stops on it, usually reporting only an unexpected token. Cleaning invisible characters out of the head of the text normally resolves it.

Can JSON store dates and binary data directly?

Neither. There is no date type, so dates become ISO 8601 strings — preferably with a time zone and millisecond precision — and there is no binary type, so bytes become a Base64 string at a cost of roughly a third more size. Genuinely large files do not belong on a JSON channel at all.

9. Three Counter-Intuitive Mistakes

Mistake one: assuming the same JSON parses identically everywhere. The syntax is universal; the numerics are not. The specification leaves range and precision to the implementation, so a 19-digit integer is rounded in JavaScript and preserved exactly in an implementation with arbitrary-precision integers. A payload that passed validation on the server may therefore no longer be the same value in the browser. Stringifying those values is what makes "identical" actually true.

Mistake two: reasoning that a bigint column justifies a JSON number. A database bigint has its own range; a JSON number's range belongs to whichever language parses it. Mapping bigint straight onto a JSON number hands the precision decision to the consumer, and the consumer is usually the least controlled part of the system. Identifiers such as IDs, card numbers and reference codes are encodings rather than quantities, and they should never have taken part in arithmetic in the first place.

Mistake three: expecting minification to save meaningful bandwidth. Measured: 44.3% on an uncompressed channel, only 13.1% more once gzip is in play. Browsers, CDNs and gateways compress text responses by default, so stripping whitespace buys far less than it appears to. Sending fewer fields, returning fewer rows, and paginating large responses all pay off much more directly.

10. Four Actions You Can Take Today

• Put the precision rules on the first page of the API spec. IDs as strings, money as integer minor units, times as ISO 8601 with milliseconds. Once those three are settled, most "the data changed by itself" reports disappear at the source.
• Define null and omission explicitly. Leave no room for interpretation between the two meanings, and state in every update endpoint what a null and a missing key each do.
• Validate and format unfamiliar JSON before comparing it. Faced with an error report, confirm the syntax and expand the structure in the JSON formatter first, then decide whether to fix the data or the parsing code; when comparing two responses, format both before diffing so a shift in key order does not flood the view with false differences.
• Attack large payloads at the data-shape level. Do not expect compression to solve a memory problem; moving to a streaming or chunked shape pays off far more than tuning a compression level.

JSON's boundary comes down to one sentence: it carries structure well and carries types and precision badly. Treat it as a neutral text transport, express everything that needs precision — IDs, money, time — as strings or integers, fill in everything that needs a type — dates, binary — by convention, and the only problem left is volume. Volume is a chunking problem, not a format problem.