Question
JSON unknown-field tolerance configuration for rolling deployments
Rin Finch
0 reputation · 15 Jun 2024, 19:05 UTC
118.2K views1
Loading…
0 reputation · 15 Jun 2024, 19:05 UTC
Goal: define a consistent policy for handling unknown JSON fields across services during rolling upgrades so that producers can emit new fields before consumers are updated without causing deserialization failures.
Constraints: major libraries diverge in default behavior — Jackson fails on unknown properties unless configured, Go’s encoding/json and Python’s json module ignore them, and Newtonsoft.Json ignores by default but can be set to error. No cross‑language standard exists for annotating field optionality, and security‑sensitive contexts may require strict parsing, which conflicts with migration flexibility.
35775 reputation · 15 Jun 2024, 20:50 UTC
Set the deserializer to ignore unknown properties at the top‑level of each runtime, then add a lightweight schema‑validation step that runs in the canary stage. In Jackson the global switch is mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false). In Go, the default is already permissive, but you can enforce strictness per call with DisallowUnknownFields() only when you want to reject; for ignore you leave the default. In Newtonsoft.Json configure MissingMemberHandling = MissingMemberHandling.Ignore and NullValueHandling = NullValueHandling.Ignore. In Python the json module ignores unknown keys automatically; a thin wrapper that checks the set of expected field names against the received keys surfaces renames or type mismatches.
jsonopt_version) while keeping the consumer unchanged.Adopt a naming convention that signals optionality, such as prefixing the key with opt_ or suffixing with _ (e.g., opt_userId or userId_). Document the convention in an OpenAPI or JSON‑Schema file and generate a schema that marks those keys as optional. This gives each service a clear contract without relying on language‑specific annotations, and the schema validation step will flag a missing optional field as a non‑fatal warning rather than a breaking error.
Use comments to ask for clarification. Post a solution as an answer.
6,300 reputation · 16 Jun 2024, 06:46 UTC
For teams adopting JSON Schema as the cross‑language contract, unevaluatedProperties: false (draft‑2019‑09 and later) provides a single source of truth that flags any field not explicitly declared — including renamed or mistyped keys — while still allowing optional fields via required: false. This works alongside the ignore‑unknown deserializer settings: the parser stays permissive, and the schema validator runs in the canary pipeline to surface breaking changes. OpenAPI 3.1 aligns with this keyword, so generated server stubs and client SDKs inherit the same rule without per‑language annotation drift.