Meme transcription: Panel 1. Two images of JSON, one is the empty object, one is an object in which the key name maps to the value null. Caption: “Corporate needs you to find the difference between this picture and this picture”
Panel 2. The Java backend dev answers, “They’re the same picture.”
Not really, if absent means “no change”, present means “update” and null means “delete” the three values are perfectly well defined.
For what it’s worth, Amazon and Microsoft do it like this in their IoT offerings.
Zalando explicitly forbids it in their RESTful API Guidelines, and I would say their argument is a very good one.
Basically, if you want to provide more fine-grained semantics, use dedicated types for that purpose, rather than hoping every API consumer is going to faithfully adhere to the subtle distinctions you’ve created.
They’re not subtle distinctions.
There’s a huge difference between checking whether a field is present and checking whether it’s value is null.
If you use lazy loading, doing the wrong thing can trigger a whole network request and ruin performance.
Similarly when making a partial change to an object it is often flat out infeasible to return the whole object if you were never provided it in the first place, which will generally happen if you have a performance focused API since you don’t want to be wasting huge amounts of bandwidth on unneeded data.
This is also how it is defined in the JSON Merge Patch RFC.
it does feel ambiguous though as even what you outlined misses a 4th case. if null means delete, how do I update it to set the field to null?
It gets more fun if we’re talking SQL data via C API: is that 0 a field with 0 value or an actual NULL? Oracle’s Pro*C actually has an entirely different structure or indicator variables just to flag actual NULLs.
Except, if you use any library for deserialization of JSONs there is a chance that it will not distinguish between null and absent, and that will be absolutely standard compliant. This is also an issue with protobuf that inserts default values for plain types and enums. Those standards are just not fit too well for patching
I’ve never once seen a JSON serializer misjudge null and absent fields, I’ve just seen developers do that.
Well, Jackson before 2.9 did not differentiate, and although this was more than five years ago now, this is somewhat of a counter example
Also, you sound like serializers are not made by developers