CAP PATCH payloads: Missing, null and empty values are different instructions
A manufacturer's custom supplier-support application changes one contact field while other saved values should remain intact.
START HERE · NO PRIOR TOPIC KNOWLEDGE NEEDED
What it is. Why it matters.
PATCH updates selected fields of a record. Leaving a field out, sending null and sending an empty string can mean different things, so an API must preserve that distinction.
Completely new to SAP?
Manufacturers use SAP to connect work such as buying components, recording inventory, planning production, shipping equipment and accounting for costs. SAP S/4HANA is an enterprise resource planning system: it connects these activities through shared business data.
Integration connects applications so they can exchange information. A delivered message still needs the receiving application to understand and accept its business meaning.
A transaction code, or t-code, is a shortcut to a task in classic SAP GUI. Fiori apps provide another way to work. Names and screens depend on the product and release; you do not need a live system to learn the concepts in this guide.

Scope and source-review notes
Scope and evidence
Source review by FAST SAP SOLUTIONS® editorial. This badge describes our editorial review; it does not represent SAP certification or independent endorsement.
CAP generic service-provider PUT/PATCH and deep-update behavior. Check the installed Node.js/Java runtime, protocol version and custom handlers.
Documentation review on 14 November 2026 using official SAP sources and indexed official excerpts where full Help text was unavailable. Scope and service or release differences are explained in the lesson. All datasets, requests and checks are illustrative; no customer SAP runtime execution or measured results are claimed.
A MANUFACTURING EXAMPLE
Update a supplier-service contact deliberately
Three different update instructions
Read the example values
- Field omitted
- No supplied instruction
- Field set to null
- Explicit null value
- Field set to empty string
- Explicit empty text
- API contract
- Defines permitted effects
Words you’ll meet in this guide
- Message
- A package of information sent between systems.
- Payload
- The business content carried in a request or message.
- API
- A defined interface for another program to use.
- Receiver
- The system to which a message or request is sent.
- CDS
- Core Data Services: reusable definitions of business data and relationships.
- HTTP
- The request-and-response protocol used by web applications and APIs.
Preview the practical steps
SEE THE CONNECTION
See it in a simple example.
A small example to make the idea concrete.
Update a supplier-service contact deliberately
A manufacturer's custom supplier-support application changes one contact field while other saved values should remain intact.
Preserve field presence as well as field value
For ordinary scalar fields under CAP’s documented generic update behavior, PATCH leaves omitted fields unchanged, while PUT can reset omitted fields to defaults or null.
Separate four instructions that a spreadsheet can hide
An input field can be absent, explicitly null, explicitly empty text or a nonempty value.
Worked case: change a city while retaining a phone number
Imagine Contact 1001 with city Berlin and phone +49-30-5550100.
Update a supplier-service contact deliberately
A manufacturer's custom supplier-support application changes one contact field while other saved values should remain intact.
Compare omitted, null and empty payload values with the service contract before sending a partial update.
| Reader | Business question | Evidence to carry forward |
|---|---|---|
| SAP developers and application teams supporting manufacturers | Update a supplier-service contact deliberately | Compare omitted, null and empty payload values with the service contract before sending a partial update. |
01 Preserve field presence as well as field value
For ordinary scalar fields under CAP’s documented generic update behavior, PATCH leaves omitted fields unchanged, while PUT can reset omitted fields to defaults or null. Explicit null and an empty string are supplied values, subject to the model and validation rules. A sender that converts every blank input to null can therefore erase data the user never intended to change. [1]
This tutorial is for integration and CAP developers building updates against a generic service provider. You need the deployed CDS model, installed Node.js or Java runtime version, protocol and custom-handler behavior. The authored Contacts example assumes ordinary persisted scalar fields and no custom normalization. Draft entities, deep compositions and custom actions require separate tests rather than automatic reuse of this scalar rule.
02 Separate four instructions that a spreadsheet can hide
An input field can be absent, explicitly null, explicitly empty text or a nonempty value. These states have different meanings. A blank spreadsheet cell alone does not tell the mapper whether to leave an existing phone unchanged, clear it or supply an empty string. Define that policy before generating JSON.
Also separate display formatting from stored value. A UI can render null and empty string identically while the database and business rules treat them differently. Inspect the serialized request and persisted result, not just the screen. A mapper’s internal object can also differ from its JSON output, so the wire payload is the relevant boundary for service diagnosis.
03 Worked case: change a city while retaining a phone number
Imagine Contact 1001 with city Berlin and phone +49-30-5550100. The user changes only city to Hamburg. A PATCH body containing only city should preserve the existing phone under the stated generic scalar contract. A mapper that inserts phone:null sends a different instruction and can clear the nullable phone if no validation prevents it.
The three payloads below should be separate fixture cases restored to the same baseline before each test. The service root is a placeholder for the application’s actual endpoint; it is not a standard SAP contact API. These requests illustrate payload meaning and have not been executed against a CAP runtime here.
PATCH <service-root>/Contacts(1001)
Content-Type: application/json
{"city":"Hamburg"}
PATCH <service-root>/Contacts(1001)
Content-Type: application/json
{"city":"Hamburg","phone":null}
PATCH <service-root>/Contacts(1001)
Content-Type: application/json
{"city":"Hamburg","phone":""}04 Make the expected state explicit before sending
For the fixture, assume phone is a nullable string and the service permits empty text. Then omission preserves +49-30-5550100, null stores null and empty text stores an empty string. If your model requires a nonempty phone or a handler normalizes values, expected results change. Read the actual annotations and handler code before claiming a universal result.
CAP’s declarative constraints include mandatory-input checks. Type constraints, not-null requirements, format checks and business validation can reject explicit values. A rejection is not a reason to replace every null with empty text until the request passes. Determine whether clearing is permitted and represent the intended instruction through the documented contract. [2]
| Payload phone member | Instruction | Expected phone after PATCH |
|---|---|---|
| Absent | No supplied phone update | +49-30-5550100 |
| null | Explicit null | Null if permitted |
| "" | Explicit empty text | Empty string if permitted |
| "+49-40-5550200" | Explicit replacement | New number if valid |
05 Build a mapper that tests presence without inventing values
For a JavaScript sender, construct the update from members actually supplied by the upstream contract. The teaching function below copies the two allowed fields only when present. It preserves null and empty text rather than guessing their meaning. It is ordinary JavaScript mapping code, not a CAP API or a complete request authorization/validation layer.
A form can load the existing phone into its model and later submit the entire model even when only city was edited. That is different from a mapper that sends only changed fields. Decide whether the client sends a full current representation or an explicit patch of user intent, then test the serializer accordingly. If a stale form still contains the old phone after another user changed it, sending the entire object can overwrite that newer value. Presence preservation and concurrency control therefore need to be reviewed together.
Define upstream blank semantics
State whether a missing source column, a blank cell and an explicit clear instruction are different inputs. Do not infer this from spreadsheet appearance.
Expected observation: The mapper receives enough information to distinguish preserve from clear.
Inspect serialized JSON
Compare the actual outgoing body with the intended allowed fields and explicit values.
Expected observation: No unsupplied phone member has been manufactured.
function buildContactPatch(input) {
const patch = {};
for (const name of ['city', 'phone']) {
if (Object.prototype.hasOwnProperty.call(input, name)) {
patch[name] = input[name];
}
}
return patch;
}
// {city:'Hamburg'} -> phone remains absent
// {phone:null} -> explicit null survives
// {phone:''} -> explicit empty text survives06 Avoid truthiness-based normalization
Expressions such as value || null collapse several values into null. For a string field, that converts empty text into null. For other types it can also collapse valid zero or false. A default-filled object that sets every missing member to null is equally dangerous for partial updates.
Use explicit policy branches: omit when no update was requested; copy a validated value when replacement was requested; send the documented clear representation only for an explicit clear action. If whitespace trimming is required, document whether whitespace-only text becomes empty, null or a rejection. That transformation is a business rule and should be tested, not hidden in a generic serializer.
07 Keep PUT and PATCH tests separate
CAP’s generic-provider documentation distinguishes omitted ordinary fields for PUT and PATCH. Replacing PATCH with PUT can therefore change more fields than the visible payload suggests. If a sender uses PUT for a partial form, compare every omitted ordinary field’s default/null behavior in the actual model rather than assuming unchanged state. [1]
Do not switch HTTP methods to work around validation without understanding the whole entity contract. A full-replacement design may intentionally use PUT, but it needs the complete intended state and applicable defaults. A partial-update design should send only requested changes through its supported method. Custom handlers can modify generic behavior, so preserve runtime and deployment identity with the test evidence.
08 Treat compositions as a separate deep-update contract
The generic-provider guide documents composition rules that differ from scalar omission. Omitted compositions have no effect for either PUT or PATCH. Explicit null for a to-one composition or an empty array for a to-many composition can remove children under the documented deep-write contract. Associations reference existing related entities and are not interchangeable with owned compositions. [1]
For a separate illustrative Contact child collection phones, suppose child IDs 11 and 12 exist. A supplied deep collection containing only ID 11 can mean that omitted existing child 12 is deleted under the documented generic deep-update behavior. It does not automatically mean “patch only child 11.” Use stable child identities and test the actual supported composition model before transmitting a partially assembled list. [1]
Confirm the documented deep-write limitations for composition conditions and the installed runtime. If the service exposes a child-specific update path or custom action, follow that contract instead. Never turn an upstream missing collection into [] merely because the mapper prefers arrays; that can become an explicit removal instruction.
09 Check concurrency and retry behavior alongside payload meaning
Correct field presence does not prevent lost updates if two clients change the same record without the application’s concurrency contract. Where ETags are configured, preserve the documented If-Match behavior and handle a conflict by re-reading and deciding which changes remain intended. Do not blindly resend a full stale entity after a conflict. [1]
A scalar assignment can be repeatable under the defined business contract, but custom handlers may trigger side effects or validations. If a timeout leaves uncertainty, inspect persisted state and the operation’s retry/idempotency design before sending another request. The payload matrix proves field semantics; it does not certify every side effect of the application.
10 Troubleshoot the first point where intention changes
Follow the value from user intent to upstream representation, mapped object, serialized body, handler processing and persisted state. The first boundary that changes omission to null is the useful repair point.
| Observation | Likely question | Next evidence |
|---|---|---|
| Phone cleared after city update | Did mapper add phone:null? | Actual PATCH body and presence policy |
| Empty text rejected | Does model require nonempty input? | Annotations and validation response |
| PUT clears unrelated fields | Were omitted scalars reset? | Method and generic/custom update behavior |
| Child records disappear | Was a composition list supplied incompletely? | Deep payload, keys and composition contract |
| Payload correct, stored value differs | Did a handler normalize it? | Deployed handler and persistence result |
| Update rejected as stale | Is concurrency control active? | ETag/If-Match and current entity version |
11 Verify positive, negative and boundary requests
Restore Contact 1001 to the same baseline before each scalar fixture. Verify the response and a subsequent authorized read of city and phone. The positive city-only PATCH should keep the old phone under the stated assumptions. Explicit null and empty string should either persist their distinct values or produce the model’s documented rejection; record which applies.
For negative tests, send an invalid format or an unauthorized field and verify the application rejects it appropriately without changing unrelated state. For boundaries, test zero and false on fields of those types in a separate model fixture, whitespace-only text and an empty update body according to the actual service contract. Do not assume an empty body must succeed.
Run separate deep-composition tests for omitted collection, [], one existing child and a new child. Check all child identities afterward, including ones absent from the payload. What closes the fix? The sender’s preserve/clear/replace policy, actual wire examples, model/runtime limits and persisted-state checks. The related idempotency and mapping lessons cover retries and transformations around that boundary.
Related services and next steps
Primary sources
Found this useful?
Share this guide with your network, or leave a like.
Your like is saved in this browser.