JSON Interoperability Guide

Fixture 01

Duplicate member names

{
  "role": "reader",
  "role": "admin"
}

RFC 8259 says object names should be unique, but this text is still accepted by many parsers. Once it becomes a typical language object or map, one value may replace the other. Which value remains is not reliably portable.

JSONClarity’s behavior: both entries retain their order, raw key spelling, value, and line/column. The second entry is linked back to the first. Repair never deletes either member.

Pointer caveat: RFC 6901 JSON Pointer names a member by its decoded key. It cannot uniquely address two members with the same name, so a copied pointer is marked ambiguous rather than extended with a proprietary syntax.

Local query grammar

The supported JSONPath subset

A query beginning with $ uses a deliberately small, non-executable subset. Plain text without $ searches decoded keys, primitive previews, and JSON Pointers instead.

• $ selects the root;
• $.name selects a simple object member;
• $['any key'] and $["any key"] use bracket-quoted names;
• $[0] selects an array index and $[*] expands one level;
• $..name recursively selects a member name;
• $..* recursively selects descendants.

Filters, scripts, slices, unions, functions, and mutation are intentionally disabled. Results keep source order, retain duplicate members, and stop at 500 matches. The visible result list mounts 24 at a time; refine the query to inspect more. Selecting a result does not run code or change the JSON, and copying produces an RFC 6901 JSON Pointer—not a claim that JSONPath and JSON Pointer are interchangeable.

Fixture 02

Numbers beyond a shared safe model

{
  "id": 9007199254740993,
  "rate": 0.12345678901234567890
}

The JSON grammar does not impose JavaScript’s numeric storage model. The integer is two greater than the largest integer in the usual interoperable safe range, and one greater than 2⁵³. The decimal carries more significant digits than common binary64 consumers preserve.

JSONClarity’s behavior: formatting emits the same raw number lexemes. The parser records risks before any optional object-like interpretation. It does not round, normalize an exponent, remove trailing decimal zeroes, or turn a number into a string.

Fixture 03

Unicode, BOMs, escapes, and controls

Escapes are source, not decoration

"a" and "\u0061" decode to the same key, so they count as duplicates in one object. Their original spellings remain different and are preserved by formatting.

Surrogate code units

A valid high/low surrogate pair represents a supplementary Unicode character. An isolated surrogate can pass the JSON grammar as an escape yet fail to represent a Unicode scalar value; the formatter keeps it and adds an interoperability warning instead of guessing a replacement.

Control characters and BOM

U+0000 through U+001F must be escaped inside strings. A leading U+FEFF byte-order mark is tolerated with a warning and can be removed only as an explicit repair. The same character elsewhere is not treated as ordinary JSON whitespace.

Source fidelity

Member order is useful even when semantics call objects unordered

Object order is not a portable semantic contract, but source order still carries practical value during review, diffs, debugging, and hand-edited configuration. The formatter preserves that order by default.

Sort keys is separate: enabling it marks the output as intentionally reordered. It never removes duplicates, never reorders arrays, and turning it off restores source order because the source tree was not mutated.

Repair contract

A proposal is not a correction

Every candidate has a source range, before/after text, explanation, and confidence. Preview applies selected edits to a copy and sends that copy through the strict parser. Apply is a separate user action. Undo restores the exact previous source text.

Before  { "ready": True, }
        -              ^  ^
Review  +              true
        -                  ,
After   { "ready": true }

The tool deliberately rejects “easy-looking” guesses such as converting undefined to null, resolving a duplicate member, rounding a number, inserting a missing complex comma, or closing an uncertain string.