Oracle Fusion REST API: How to Clear a Field with PATCH (Null Values)

Two separate, unanswered threads on Cloud Customer Connect ask the same question in different words: “How do I blank a value using REST API PATCH?” and “How do I pass a null value from an item update through the REST API PATCH method?” Neither has an accepted answer. If you’ve sent {"SomeField": null} in a PATCH request and watched the field stay exactly as it was — no error, no change — you’ve hit the same wall.

This post covers why that happens and the actual paths that work.

Why `null` doesn’t behave like a plain merge-patch

In a generic JSON merge-patch (RFC 7396), sending a field with value null means “delete this field.” Oracle Fusion’s REST layer doesn’t follow that convention uniformly, because the REST resource sits on top of a real Oracle business object — and that business object’s own validation rules decide whether a null is even legal for a given attribute, independent of what the REST framework itself would otherwise allow.

That produces three different outcomes depending on the attribute, and there’s no single flag that tells you which one you’ll get:

It works — the attribute is cleared, you get 200 OK, a follow-up GET shows the field empty.
It’s silently ignored — you get 200 OK, nothing in the response looks wrong, but a follow-up GET shows the old value untouched. This is the one that costs people hours, because the request “succeeded.”
It’s rejected — you get a 400 Bad Request with a business-object validation message, because the attribute has a rule (required-if-X, format constraint, etc.) that a null value violates.

Step 1: check whether the attribute is even updatable

Before touching null, confirm the field allows updates at all. Every resource’s /describe endpoint returns attribute-level metadata including an updatable flag:

GET /hcmRestApi/resources/latest/workers/describe
Accept: application/vnd.oracle.adf.resourceitem+json

If updatable is false for the attribute you’re trying to blank, no value — null or otherwise — will change it through PATCH. That rules out outcome 1 immediately and tells you outcome 2 or 3 is coming.

Step 2: plain attributes usually accept `null` directly

For a straightforward, updatable, non-flexfield attribute, sending null in the PATCH body generally does clear it. Using the Workers endpoint’s real phones child resource (a genuine child on /workers, with PhoneNumber as a queryable field per the catalog):

PATCH /hcmRestApi/resources/latest/workers/{workersUniqID}/child/phones/{PhoneId}
If-Match: "<etag-from-a-prior-GET>"
Content-Type: application/vnd.oracle.adf.resourceitem+json

{
  "PhoneNumber": null
}

You still need a fresh If-Match ETag on the parent resource, or you’ll get a 412 Precondition Failed before the null value is even evaluated — see the ETag / If-Match guide for the capture-and-retry flow. This is the one gotcha every write request shares, null-clearing included.

Step 3: descriptive flexfield segments are the least reliable case

Both Cloud Customer Connect threads that motivated this post specifically mention DFF columns — and that’s the category where null is least predictable. A DFF segment’s nullability is governed by the flexfield’s own configured validation (required-context rules, value-set constraints), not by the REST layer. Per the DFF/EFF/DDF guide, segments live inside a context-scoped child resource (workersDFF on Workers, for example) keyed by __FLEX_Context:

PATCH /hcmRestApi/resources/latest/workers/{workersUniqID}/child/workersDFF/{DFFUniqId}
If-Match: "<etag-from-a-prior-GET>"
Content-Type: application/vnd.oracle.adf.resourceitem+json

{
  "__FLEX_Context": "US Passport Info",
  "Attribute1": null
}

If this comes back 200 OK but the segment value is unchanged on a follow-up GET, the segment is configured as required-within-that-context and Oracle’s validation is silently refusing the null (outcome 2 above). There’s no REST-level override for that — it’s a flexfield configuration decision, so the fix is on the functional/configuration side (make the segment optional) rather than the integration side.

Step 4: date-effective objects — null on the right slice

If the attribute lives on an effective-dated object (an assignment field, not a person-level field), clearing it is also a question of which date slice you’re updating. Sending RangeMode=UPDATE when you meant RangeMode=CORRECTION (or vice versa) can make a null value appear to do nothing, because you cleared the wrong effective-dated row rather than the one you’re looking at:

PATCH /hcmRestApi/resources/latest/workers/{PersonId}
Effective-Of: RangeMode=CORRECTION;RangeStartDate=2026-08-01;RangeEndDate=4712-12-31
If-Match: "<etag-from-a-prior-GET>"
Content-Type: application/vnd.oracle.adf.resourceitem+json

{
  "SomeAssignmentAttribute": null
}

Quick diagnostic table

Symptom	Likely cause	Where to check
`400 Bad Request` on the PATCH	Attribute has a validation rule that rejects null	Error message body usually names the rule
`200 OK`, but a follow-up GET shows the old value	Attribute not updatable, or DFF segment required-in-context	`/describe` metadata (`updatable` flag), flexfield context config
`412 Precondition Failed`	Stale `If-Match` ETag	Re-GET, capture a fresh ETag, retry
Wrong date slice cleared	`RangeMode` mismatch on an effective-dated object	`Effective-Of` header — CORRECTION vs UPDATE

Exploring attribute metadata without a live instance

Knowing whether an attribute is updatable — and whether it belongs to a DFF-governed child resource — is exactly the kind of thing you’d otherwise have to discover by trial and error against a live Fusion instance. OPAL bundles the full Oracle Fusion Cloud OpenAPI specification (HCM, FSCM, and BPM) locally, so you can inspect every field’s type and operators, every child resource, and every finder offline — no instance, no waiting on a sandbox.

This post is part of our complete Oracle Fusion API guide — base URLs, authentication, q filters, finders, and common errors in one place.

Why null doesn’t behave like a plain merge-patch