Null, Empty, Zero, or Missing: How to Avoid Changing Meaning in JSON for an API

An Intentional Abridgment: Start with the Representation

This guide is an intentional abridgment focused on a practical distinction: the JSON shape of a value and the meaning assigned to it by a particular API are not the same thing. It does not attempt to prescribe a universal update, validation, or testing policy. Those decisions depend on the documented contract for the endpoint and operation you are using.

When reviewing a payload, describe exactly what it contains before deciding what it means. A property can be present with an explicit value, or it can be absent from the object. Those are different representations. Saying only that a field is “empty” can conceal which representation you intend to send or have received.

• First identify the JSON representation.
• Then consult the contract for the specific endpoint and operation.
• If the contract does not define a case, record that meaning as unresolved.

Four Different JSON Representations

In a JSON object, null, an empty string (""), zero (0), and an omitted property are distinct representations. The JSON value null is an explicit value, not the same thing as leaving out a property. IBM’s JSON documentation describes null as a special JSON value that can be used with different data types, including arrays, objects, and numeric types. That description supports the distinction between an explicit null value and an absent key; it does not define how every API interprets either one.

An empty string is a string containing no characters. Zero is a number. An omitted property has no key in the object at all. For example, {"note": null}, {"note": ""}, and {"note": 0} all include the key note, with different values. The object {} does not include note.

These examples show shape, not universal behavior. They do not establish whether an API accepts a value, stores it, ignores it, or uses it to change an existing resource. Treating all four cases as interchangeable risks obscuring what the payload actually says.

• null: an explicit JSON value.
• "": an explicit empty string.
• 0: an explicit number.
• Missing property: the key is not included in the object.

Let the Endpoint Contract Define the Meaning

The representation alone does not determine what an API will do. There is no universal rule, established by these examples, for how an omitted property, null, an empty string, or zero is interpreted when creating or updating a resource. Consult the contract for the exact endpoint and operation, rather than borrowing an assumption from a different field or API.

Check the documented type and whether the property is required or may be null. For an update operation, look specifically for documented behavior when the property is omitted, set to null, or supplied as an empty string or zero. A statement about one of these cases does not settle the others. Likewise, a rule for one operation does not automatically define a different operation.

If the contract provides an example, read it as an example of the documented payload unless it explicitly explains the behavior you need to know. The presence of a value in an example is not, by itself, a general rule for every possible value. If the needed case is not described, keep the interpretation unresolved and seek clarification rather than inferring an outcome.

• Separate what the contract explicitly defines from what it leaves unspecified.
• Do not assume similar fields or different operations share the same rule.
• Record an unresolved case instead of converting an assumption into a requirement.

Keep Source Data and JSON Output Distinct

A useful mapping distinguishes the state received from the representation intended for the outgoing JSON. For a comment, for instance, record whether no answer was provided or a blank answer was provided. For an amount, distinguish an empty input from the number zero. These descriptions capture the source state; they do not decide how that state must be represented in an API request.

Keep three questions separate: What was received? What meaning does the application intend to preserve? What does the endpoint contract say to send? The answer to the third question should guide the output representation. If the contract does not settle it, mark the output decision unresolved instead of silently filling the gap.

Also preserve the distinction between strings and numbers in examples. "0042" is a string, while 42 is a number. This comparison shows different JSON types; it does not establish which type a particular API requires. Do not rewrite one form as the other unless the relevant contract and intended meaning support that decision.

• Useful mapping fields: source field | received state | intended meaning | documented rule | JSON output.
• Make clear whether an example omits a key or includes it with an explicit value.
• Keep unanswered mapping decisions visible rather than disguising them as settled conversions.

Use Representative Examples to Expose Open Questions

Representative examples can make a payload discussion more precise, provided they are presented as cases to check rather than as universal instructions. For a field that matters to your integration, prepare separate examples for an omitted property, null, an empty string, and zero where those representations are applicable. Compare each example with the endpoint contract and note which cases it defines.

For example, a review might display {"note": null}, {"note": ""}, {"note": "Text"}, and {} side by side. The first three include note; the last does not. The examples alone do not say whether any of them are accepted or what effect they have. Their purpose is to make the difference visible and to identify exactly which behavior needs confirmation.

If the property is documented as a number, a string example may not be relevant to that field; if it is a string, a numeric example may not be relevant. Use examples that match the documented type, and avoid presenting an inapplicable example as a valid request. When type or behavior is unclear, state that uncertainty rather than guessing.

• Compare only cases relevant to the property's documented type and operation.
• Label each example by its JSON shape, not by an assumed effect.
• Use the comparison to locate unanswered contract questions.

Validation and Contract History

Validation should be discussed in terms of the rules actually documented for the field and endpoint. Do not infer that a payload is valid merely because its JSON syntax is clear, or that a representation is invalid merely because its meaning is not explained in a short example. Syntax, documented type, and API-specific behavior are separate questions; the available evidence here does not establish the rules for any particular endpoint.

For .NET developers, Microsoft Learn describes configuring System.Text.Json serialization and deserialization to respect nullable annotations. This is a capability of that .NET serialization library; it is not a universal JSON rule and does not specify how an unrelated API interprets omitted properties, empty strings, or zero. Keep implementation-specific guidance within that scope.

When you document an integration decision, keep the relevant contract language with the decision and identify the endpoint and operation it concerns. If a later review uses a different contract description, compare what each description explicitly says rather than assuming the meaning stayed the same. This record helps readers distinguish a confirmed rule from a question that still needs clarification; it does not create behavior that the API documentation does not state.

• Keep JSON representation, documented type, and API-specific interpretation distinct.
• Scope .NET nullable-annotation guidance to System.Text.Json and the relevant configuration.
• Record the contract basis for a decision and flag cases the available documentation does not resolve.

A Compact Review Checklist

Before sending or reviewing a payload, identify whether the property is absent or present. If present, identify its actual value and type: null, a string, or a number are not interchangeable labels. Then consult the contract for the exact endpoint and operation, including any documented requirements about the property and the cases that matter to your request.

For a transformation or mapping, compare the source state, intended meaning, documented rule, and proposed JSON output. If any link is based on an assumption, mark it. When the documentation does not define the behavior you need, the safe conclusion is not that one representation has a particular effect; it is that the behavior remains unresolved.

This checklist is deliberately narrow. It helps make payload shape and unanswered questions explicit, but it does not replace the API contract or establish universal semantics for updates. The contract remains the authority for the specific operation.

• Is the key present?
• If present, what exact value and JSON type does it have?
• What does the specific endpoint contract say about this case?
• Which part, if any, remains unresolved?

Frequently asked questions