skip to content

What do the ignoreUnknownKeys and isLenient flags on the Json { } builder do, and when would you enable each?

level: middleimportance: must knowfreq 70%

answer

  1. ignoreUnknownKeys = skip extra keys
  2. isLenient = relax syntax (unquoted)
  3. default Json is strict
  4. orthogonal flags, set independently
  5. @JsonIgnoreUnknownKeys scopes it per class

basics

~10 s

ignoreUnknownKeys lets decoding skip JSON keys your class doesn't have instead of failing. isLenient relaxes strict JSON parsing, allowing unquoted keys/values. Enable them mainly when consuming flexible third-party JSON.

solid answer

~40 s

By default Json is strict. ignoreUnknownKeys = true tells the decoder to silently skip object keys that have no matching property, instead of throwing SerializationException — essential when an API adds fields you don't model. isLenient = true relaxes the JSON grammar: it permits unquoted string literals and unquoted map keys and is more forgiving of malformed input (it's used internally by quirky sources). The two are independent: ignoreUnknownKeys is about *extra* keys; isLenient is about *syntax* strictness. For robust API clients you usually set ignoreUnknownKeys = true and leave isLenient = false so genuinely broken payloads still fail fast. Note ignoreUnknownKeys can be overridden per-class with @JsonIgnoreUnknownKeys (Kotlin 2.x). isLenient should be used sparingly because it masks real errors.

go deeper

for a junior

Knows ignoreUnknownKeys avoids crashes on extra fields and that Json is strict by default.

for a middle

Clearly separates the two flags and picks ignoreUnknownKeys=true / isLenient=false for API clients.

for a senior

Discusses per-class @JsonIgnoreUnknownKeys, the risk of masking typos, and fail-fast tradeoffs.

for a principal

Frames it as a contract-robustness policy: tolerate forward-compatible growth, reject malformed input, scope leniency narrowly.

## Strict by default The default `Json` instance is intentionally strict: any JSON that doesn't match your model fails with a `SerializationException`. Two builder flags loosen this in different, independent ways. ## ignoreUnknownKeys **What it controls:** unknown *object keys* during decoding. - Default `false`: if the JSON object contains a key with no matching `@Serializable` property, decoding throws `SerializationException: Unexpected JSON key`. - `true`: the decoder skips those keys silently. ```kotlin @Serializable data class User(val id: Int) val lax = Json { ignoreUnknownKeys = true } lax.decodeFromString<User>("""{"id":1,"nickname":"x"}""") // User(id=1) — nickname skipped ``` Use it when consuming an evolving API that may add fields you don't model. In Kotlin 2.x you can scope it to one class with the `@JsonIgnoreUnknownKeys` annotation instead of globally. ## isLenient **What it controls:** the JSON *grammar* (syntax), not which keys exist. - Default `false`: requires well-formed JSON — quoted keys and quoted string values. - `true`: permits unquoted string literals and unquoted map keys, and is generally more forgiving. ```kotlin val lenient = Json { isLenient = true } lenient.decodeFromString<User>("{id: 1}") // accepted despite unquoted key ``` ## They are orthogonal - `ignoreUnknownKeys` = tolerate *extra* keys. - `isLenient` = tolerate *loose syntax*. Enabling one does not enable the other. A common production setup is `ignoreUnknownKeys = true` with `isLenient = false`, so you tolerate schema growth but still reject genuinely corrupt input. ## Caution `isLenient = true` masks malformed payloads and should be reserved for talking to non-conforming sources. `ignoreUnknownKeys = true` can hide typos in property names you *expect* to map.

  • If ignoreUnknownKeys is false and the payload has a typo'd extra key, what happens?
    Decoding throws SerializationException because the key has no matching property; that's why API clients often set it true.
  • How can you allow unknown keys for one class only?
    Annotate that class with @JsonIgnoreUnknownKeys (Kotlin 2.x) instead of flipping the global flag.

saying these in an interview costs you the question

  • Saying isLenient makes the decoder ignore unknown keys
  • Saying ignoreUnknownKeys changes JSON syntax rules
  • Recommending isLenient = true for normal API consumption
  • Believing one flag implies the other

context

resolving links…