There are all kinds of solutions ("why not just use undefined instead?"), but whichever it is, a decision has to be made, documented, remembered, and edge cases decided. Whatever you have, now the API has a non-obvious custom spec just for that API alone. It's not a "why not just".

I guarantee, another dev would come along, look at the custom spec, and think "Why not just use JSON Patch?"

undefined would in theory be slightly "better" for deleting values (the value { key: undefined } serializes to {}), but, alas, it isn't supported by JSON, so you'd have to use a custom serializer and deserializer for it to even work.

I would expect in such cases that JSON Merge Patch, and its media type, would be used to head off bikeshedding discussions.

https://www.rfc-editor.org/rfc/rfc7396.html

And how do you set a field to null?

To delete something, I imagine you set it to undefined. I don't know anyone who uses the undefined state at rest for anything interesting.

JSON doesn't have undefined, only null

the partial updates approach works ok for updating 'schemaful' data, where it could only ever mean to set the field to null and could never delete the field from the object altogether

but for editing a JSON document or other schemaless data then both operations are possible and you'd need to be able to distinguish them

Same way.

So you set a field to `null` using

    { "foo": null }

and you delete a field using

    { "foo": null }

don't you see a bit of an issue there?

as in `{null:null}` ?

won't that set a field called 'null', to the value null?

As in { "foo" : null }

You can interpret a null field the same as a missing field. You only need to worry if you have arbitrary dictionary keys and need to differentiate a null value from an missing key.

> You can interpret a null field the same as a missing field.

Not in the general case no, they are two different states, which may have entirely different semantics.

For instance a missing field can mean "don't touch this field" while a field set to null means "set this field to null".

Some schemas might opt to ignore this distinction and collapse the states, but that is a specific decision, and an express loss of information.

> You only need to worry if you have arbitrary dictionary keys and need to differentiate a null value from an missing key.

There are other situations where that's an issue, like the above, or when you're using the object as a set (which JSON doesn't have), or when you've defined the schema to never have missing fields (but possibly have some set to `null`) so clients will break, ...

Null could imply the field was present and a value not entered or not necessary. Missing could imply the field was never known about at all. The context is important.

Null != missing.