Serialization Formats

Normally the type name is a field inside the object (discriminator mode). But that only works when the value is a JSON object. For non-object values (like a primitive), the library wraps it as a two-element array [typeName, value]. You can also force array mode.

For a nested object, hand the encoder the nested type's own serializer instead of encoding fields yourself. For a field that may be null, use the nullable-element methods so null is written and read correctly instead of crashing.

These flags make the parser more forgiving. Forgiving is convenient but can silently accept or change attacker data. For untrusted input, prefer strict settings so unexpected data fails loudly instead of slipping through.

JsonObject and JsonArray are immutable. JsonObject acts like a Map and keeps insertion order; equality compares contents. A common gotcha: numbers are stored as text inside JsonPrimitive, so 1 and 1.0 are different primitives and aren't equal.

Polymorphic encoding only happens when you serialize through the base type, not a concrete subtype. Generic type arguments still need their own serializers, and a nested sealed property must itself be polymorphically encoded. The discriminator key must not collide with a real field name.

Create a few shared, reusable Json instances configured for their job: strict for output, tolerant (ignoreUnknownKeys) for input. Don't build Json { } per call, and derive variants with Json(from = base) { ... }.

Don't hard-rename. Add the new field with a default, keep accepting the old one, ignore unknown keys during transition, then drop the old field only after all old payloads are gone.