Handling optional fields in an API payload

Treat an optional field as a contract decision, not a blank to fill. In JSON, an absent property differs from one explicitly set to null; an empty string is a third value. An API may use these differences to mean “leave unchanged”, “clear this value” or “set an empty value”. Confirm that behaviour before mapping a payload.

Meaning of Missing, Null and Empty in API Payloads

Read the destination rule

For each field, note whether it is always required, required only for a particular event, optional or read-only. Record its allowed type and whether null is valid.

A JSON Schema can specify required properties separately from property definitions. Defining a field in properties does not automatically require it. A sample payload alone is a poor contract: it may contain optional fields that are not present in other events.

Check the API operation. A create request and a partial update can handle absence differently. If the destination's update semantics are unclear, test them with a disposable record or ask the provider. Never translate all missing source values to null without knowing whether that clears stored data.

Map the cases deliberately

Consider a customer record with an optional phone number. If the source did not send a phone field because only the email changed, the workflow may need to omit phone from a partial update.

If the user explicitly removed the phone number, the destination may require null or another documented clearing operation. If the source sent an empty string, decide whether that is a valid value or a data-entry error. These are separate branches.

Use conditional mapping rather than a default that disguises uncertainty. When a field is needed for downstream action but missing, reject or hold that event with a clear reason. For an optional field that truly has no value, omit it if the receiving contract permits omission. Preserve any distinction between “unknown” and “not applicable” that matters to reporting.

Test all three states

Build test payloads for present valid value, absent property and explicit null. Add empty string, wrong type and a field that is required only in one event state. Validate the outgoing payload against a schema, then inspect the receiving record. A parse step in a workflow can expose fields for later actions, but parsing does not decide the business meaning of missing values.

Keep the chosen behaviour in the mapping document. That one line can prevent a routine update from erasing information in a connected application.

Test Cases for Optional Fields