Start with the operation, not the schema
An update contract should first state what each input state asks the service to do. Schema validation can distinguish payload shapes, but the product team must decide whether a state preserves, clears, replaces, resets, or rejects stored data.
A member that is absent from an object is a different JSON situation from a member whose value is null. Treat that distinction as an input to the business rule rather than assuming that either state has an inherent update meaning.
| Payload fragment | Input state | Proposed service action | Schema direction |
|---|---|---|---|
{} | Display name omitted | Leave the saved display name alone | Do not list the field in required for this partial-update request |
{"displayName":null} | Explicit null | Reject, because this field must have text when supplied | Allow only the string type for this field |
{"displayName":""} | Empty string | Reject, because a blank label is not useful | Add a field-level constraint that excludes the empty string |
{"nickname":null} | Explicit null | Clear the optional nickname | Permit both the chosen text form and null for this field |
{"tags":[]} | Empty array | Replace saved tags with no tags | Use an array schema and decide whether zero items are valid |
This table is a design example, not a documented API result. A different domain may reasonably reject null, use it as a reset request, or give an empty collection another meaning.
Map each field independently
In an object schema, entries in properties associate individual names with their own schemas. That lets an update contract make nickname nullable while keeping displayName non-null when it appears.
The required keyword checks whether an object contains specified names. It should therefore express presence requirements, not serve as a proxy for a field's permissible values.
A schema whose declared type is only null accepts the JSON null value, not values such as false, 0, or an empty text value. If a field may carry either text or null, model that accepted set explicitly under the selected JSON Schema dialect.
Decide how to handle names you did not expect
The properties keyword alone does not reject object members that it does not name. Use additionalProperties when the contract needs a rule for unmatched names, and document whether a client typo should fail or be tolerated.
If patterned field names are part of the contract, patternProperties attaches schemas to names selected by regular expressions. Those expressions are not implicitly bounded to the whole name, so add anchors when a whole-name match is intended.
Be cautious when composing object schemas. A branch that sets additionalProperties to false recognizes declarations made in that same branch; placing fields in another allOf branch can consequently reject an intended extension.
Choose and test the policy deliberately
Write a per-field decision record before implementation: omission behavior, null behavior, permitted empty representations, valid populated values, and unknown-name handling. Then turn that record into representative acceptance and rejection cases for the chosen validator and schema draft.
- Use omission for “leave untouched” only when the operation explicitly defines that behavior.
- Reserve null for a deliberate domain state or command, rather than using it interchangeably with every empty representation.
- Give empty strings, lists, and objects field-specific rules; their business effect is a product decision.
- Consider separate create and partial-update schemas when presence requirements differ substantially.
The referenced material explains JSON value and object-schema mechanics, but it does not assign a universal meaning to clearing a value or to empty strings, arrays, and objects in an update workflow. Confirm the deployed JSON Schema draft and validator behavior before making the table an operational contract.
Limits and alternatives
A strict approach can reject both null and empty values for most fields, making clients send populated replacements only. Another approach can accept null as a clear instruction while treating omission as no action. A third can use explicit empty collections or text as domain values and reserve null for a distinct state. None is automatically correct; choose based on persistence behavior, client expectations, and audit needs.
This guidance does not establish a particular API's runtime behavior, authorization model, storage semantics, or validator configuration. The illustrative table must be reviewed against the implementation's selected schema version and tested with its actual validation stack.