BigInt over JSON: define a lossless field contract before adding a replacer

What it is

MDN documents that JSON.stringify does not serialize BigInt values by default and raises a TypeError. A replacer or explicit conversion can encode them, but the receiver must know how to reconstruct the intended type. Converting through Number can lose precision, so the transport representation is part of the schema contract. MDN BigInt

Why it matters

An agent may fix the exception by applying Number to every BigInt. That solves serialization while potentially changing identifiers or counters. Decide whether the receiver needs arithmetic, identity comparison or display, and choose an explicit representation that preserves the required information.

How to apply

• Inventory the affected fields and their allowed ranges. Distinguish identifiers from quantities; an identifier need not become a numeric runtime type merely because it contains digits.
• For a decimal-string representation, specify sign, leading-zero and empty-string rules in the schema. Convert directly from the BigInt to its string form, avoiding a Number intermediate.
• If using a tagged object, define its exact shape and collision policy. Do not let arbitrary user objects become privileged numeric values just because they contain a conveniently named key.
• Propose round-trip fixtures for zero, negative values when allowed, and integers outside the receiver's safe Number range. Assert exact value equality after reconstruction.
• Test malformed encodings and ensure validation fails with a clear field error. Keep the same schema in producer, consumer and stored fixtures.

Pitfalls

A generic JSON reviver cannot infer the original type of every decimal-looking string. A global prototype modification also affects unrelated serialization, so review its scope before adopting it. Other languages may have different native integer ranges; test each actual consumer. This article proposes a lossless contract review and does not claim a universal encoding standard or executed interoperability results.