Line-by-line text diffs work great for source code, and quick web diff tools work fine until production data stops behaving like formatted prose. Once you compare real API payloads, Kubernetes manifests, CSV exports, or copy-pasted text from docs, four quiet failure modes show up repeatedly: two different 64-bit IDs look identical, naive key sorting breaks YAML anchors, reordered CSV rows hide real cell changes inside a wall of red and green lines, and lookalike Unicode spaces slip past code review.
Here is why those four bugs happen, how to reproduce them, and how to handle them reliably in a browser-local workflow.
1. 64-bit integer collisions and dropped duplicate keys in JSON.parse()
Many online JSON format-and-diff tools normalize input by running JSON.parse() followed by JSON.stringify(obj, null, 2). In JavaScript, every parsed JSON number becomes an IEEE-754 double-precision float, which only represents integers losslessly up to Number.MAX_SAFE_INTEGER (9007199254740991, or 2^53 - 1).
You can verify the silent collision in any JS console:
JSON.parse('{"id":9007199254740992}').id === JSON.parse('{"id":9007199254740993}').id
// -> true (both coerce to 9007199254740992)
JSON.stringify(JSON.parse('{"threshold":1e400}'))
// -> '{"threshold":null}'
Running JSON.parse() + JSON.stringify() on Snowflake IDs, Stripe/payment trace IDs, or large integers introduces two more blind spots:
-
Lost duplicate keys: If a broken serializer emits
{"role":"viewer","role":"admin"},JSON.parse()silently keeps only the last value, hiding the duplicate key during comparison. -
Rewritten decimal formatting:
1.00becomes1, which can mask formatting regressions in stringified contracts.
What works instead: Parse JSON using a lossless tokenizer or source-mapped AST (jsonc-parser or json-source-map) rather than materializing native JS Number objects. Extract key paths, original number lexemes, and UTF-16 source spans directly from the token tree, emit explicit warnings for duplicate keys, and only serialize back the exact original scalar tokens when sorting keys.
2. Naive alphabetical YAML key sorting breaking << merge keys and anchors
When two tools emit YAML manifests with identical content in different key orders, a plain text diff marks half the document changed. Sorting mapping keys alphabetically collapses the formatting noise—until a manifest uses anchors (&) and aliases (*) or << merge keys:
defaults: &d
retries: 2
timeout: 10s
app:
<<: *d
replicas: 3
If a diff normalizer blindly sorts the top-level mapping alphabetically, app moves above defaults. Strict YAML parsers reject the resulting document immediately with an unresolved alias error because &d has not been defined yet. Sorting mappings that contain << merge keys can also alter override order or drop comment attachments.
What works instead: Walk the YAML AST with structure-aware guards:
-
Keep sequence (
- item) order untouched so arrays like container args or ordered pipeline steps are never reordered semantically. -
Sort mapping keys recursively only where safe—if a mapping contains
<<merge keys or cross-sibling anchor-before-alias dependencies, preserve sibling order at that level with a clear warning while still sorting independent child maps. -
Map source lines to YAML paths (like
runtime.replicasorservices.api.tags[0]) so clicking a changed line shows both its structural path and exact scalar values.
- Deep dive & interactive example: Compare YAML ignoring key order safely | Try the YAML example live
3. Shuffled CSV exports and silent leading-zero coercion
Export the same database table after two queries with different ORDER BY clauses (or after someone opens and re-sorts in a spreadsheet), and line-based diff flags almost every row as deleted and re-added. Two real price or status edits disappear inside 500 noisy diff hunks.
Tools that try to "fix" this by loading both CSVs into generic typed tables often cause a second bug: string identifiers like SKU 0042 coerce to 42, and 29.00 coerces to 29.
What works instead: Treat every CSV/TSV cell as an immutable string, and align rows on an explicit shared key column (for example, sku or id):
- Match rows by exact key string while preserving original line numbers from both files so you know where every edit lives in the raw export.
- Align columns by header name if columns moved between exports.
Warn clearly on duplicate keys (pairing duplicates in order of appearance) and fall back cleanly to line diff with row diagnostics if a CSV has unclosed quotes or mismatched column counts.
Deep dive & interactive example: Compare CSV files by key column | Try the CSV SKU example live
4. Invisible Unicode twins and final-newline mismatches
Two configuration values, SQL predicates, or Markdown headings can render identically in almost every editor yet fail equality checks:
| Code point | Name | Common origin |
|---|---|---|
U+0020 |
ASCII Space | Normal keyboard space |
U+00A0 |
No-Break Space (NBSP) |
Copy-paste from browsers, Slack, Word, rich docs |
U+200B |
Zero-Width Space (ZWSP) |
Zero-width wrappers, PDF extraction, web editors |
U+3000 |
Ideographic Space | CJK IME (全角スペース) left active in config/code |
U+FEFF |
Byte Order Mark (BOM) |
Windows/spreadsheet UTF-8 exports at index 0
|
A standard diff without character-level markers shows two identical-looking lines marked red and green. Similarly, one file ending in \n and the other omitting the trailing newline produces an unexpected mismatch at EOF that trips up checksums, Git patches, and CI linters.
What works instead: Surface explicit visible markers (NBSP, ZWSP, IDEOGRAPHIC, BOM, trailing [EOF] newline state) alongside exact UTF-16 column offsets so you can spot which character differed without manually inspecting hex dumps.
- Deep dive & interactive example: Detect zero-width, NBSP, and full-width spaces | Try the invisible-character example live
Try them locally (Disclosure & Honest Limits)
Disclosure: I built Folio, the browser-local workspace linked in the guides above.
Folio runs document parsing and diffing inside local Web Workers with a strict Content Security Policy (connect-src 'none'), no backend uploads, no user accounts, and no in-app telemetry. You can also export a script-free, print-to-PDF HTML comparison report directly from the client via More actions -> Export HTML (PDF-ready) (HTML audit report guide).
Honest limits to keep in mind:
- Supports UTF-8 text files up to 20 MB per side (no binary
.xlsx, PDF, Word, or image diffing). - XML and general source code currently compare as text rather than structural ASTs.
- Large diffs paginate at 500 rows to keep the browser responsive, and saved workspaces stay local in your browser's IndexedDB.
If you have hit other edge cases comparing YAML manifests, JSON API snapshots, or exported CSVs, I would love to hear which patterns trip up your workflow.
Top comments (0)