{"id":1502,"date":"2026-11-16T18:00:00","date_gmt":"2026-11-16T18:00:00","guid":{"rendered":"https:\/\/wade.one\/blog\/?p=1502"},"modified":"2026-11-12T23:15:13","modified_gmt":"2026-11-12T23:15:13","slug":"missing-and-null-need-different-rules-in-a-patch-api","status":"publish","type":"post","link":"https:\/\/wade.one\/blog\/2026\/11\/16\/missing-and-null-need-different-rules-in-a-patch-api\/","title":{"rendered":"Missing and Null Need Different Rules in a PATCH API"},"content":{"rendered":"<p>If I leave a field out of a partial update, I usually mean &#8220;leave it alone&#8221;. If I deliberately clear it, I expect the API to have a way to express that. Collapsing both requests into the same value is a small implementation shortcut that can make an edit form surprisingly destructive.<\/p>\n<p>Consider a profile with an optional nickname. These payloads need a documented meaning:<\/p>\n<pre><code>{}<\/code><\/pre>\n<pre><code>{&quot;nickname&quot;: null}<\/code><\/pre>\n<p>For an endpoint using <a href=\"https:\/\/www.rfc-editor.org\/rfc\/rfc7396.html\">JSON Merge Patch<\/a>, the first leaves the nickname unchanged and the second removes that member from the target JSON document. That format uses <code>application\/merge-patch+json<\/code>. Its rules do not automatically apply to every endpoint called PATCH; choose and document the request format rather than expecting the HTTP method to explain the body.<\/p>\n<p>There is a useful limitation here too. Merge Patch gives <code>null<\/code> a removal meaning, so it is awkward when storing an explicit JSON null is itself a meaningful operation. Arrays are replaced as a whole rather than edited item by item. If those rules do not fit the resource, choose a format that does. Calling an endpoint a partial update does not settle those decisions.<\/p>\n<p>The implementation needs to preserve field presence from parsing through to persistence. A request mapper that fills every omitted property with <code>null<\/code> has already lost the information. So has validation that supplies a default before the update code can tell whether the client sent the field. Defaults that make sense when creating a record can be wrong when editing one.<\/p>\n<p>I would make the contract explicit for the fields the endpoint allows people to change. Omitted means unchanged; a supplied value is validated and applied; an explicit clear is either supported or rejected with a useful explanation. An empty string should follow the field&#8217;s own rules too. It might be valid text, an invalid value or a documented way to clear something, but it should not acquire a meaning by accident.<\/p>\n<p>This is worth a small test through the real request handling: change one field and check that an omitted neighbouring field survives, then explicitly clear the optional field and check the intended result. A unit test of the final update function can miss the mapper that erased the distinction several steps earlier.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Leaving a field out and deliberately clearing it are different requests. A partial-update endpoint needs to preserve that distinction.<\/p>\n","protected":false},"author":0,"featured_media":0,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_jetpack_newsletter_access":"","_jetpack_dont_email_post_to_subs":false,"_jetpack_newsletter_tier_id":0,"_jetpack_memberships_contains_paywalled_content":false,"_jetpack_hide_featured_image":false,"_jetpack_featured_image_duplicate_dismissed":0,"_jetpack_feature_clip_id":0,"_jetpack_memberships_contains_paid_content":false,"footnotes":"","jetpack_publicize_message":"","jetpack_publicize_feature_enabled":true,"jetpack_social_post_already_shared":true,"jetpack_social_options":{"image_generator_settings":{"template":"highway","default_image_id":0,"font":"","enabled":false},"version":2},"jetpack_post_was_ever_published":false},"categories":[13],"tags":[66,331,332],"class_list":["post-1502","post","type-post","status-publish","format-standard","hentry","category-programming","tag-api","tag-json-merge-patch","tag-validation"],"yoast_head":"<!-- This site is optimized with the Yoast SEO plugin v28.8 - https:\/\/yoast.com\/product\/yoast-seo-wordpress\/ -->\n<title>Missing and Null Need Different Rules in a PATCH API - wade.one<\/title>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/wade.one\/blog\/2026\/11\/16\/missing-and-null-need-different-rules-in-a-patch-api\/\" \/>\n<meta property=\"og:locale\" content=\"en_GB\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Missing and Null Need Different Rules in a PATCH API - wade.one\" \/>\n<meta property=\"og:description\" content=\"Leaving a field out and deliberately clearing it are different requests. A partial-update endpoint needs to preserve that distinction.\" \/>\n<meta property=\"og:url\" content=\"https:\/\/wade.one\/blog\/2026\/11\/16\/missing-and-null-need-different-rules-in-a-patch-api\/\" \/>\n<meta property=\"og:site_name\" content=\"wade.one\" \/>\n<meta property=\"article:published_time\" content=\"2026-11-16T18:00:00+00:00\" \/>\n<meta property=\"og:image\" content=\"https:\/\/wade.one\/blog\/wp-content\/uploads\/2015\/02\/Wade-Logo-cropped.png\" \/>\n\t<meta property=\"og:image:width\" content=\"1518\" \/>\n\t<meta property=\"og:image:height\" content=\"1506\" \/>\n\t<meta property=\"og:image:type\" content=\"image\/png\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:creator\" content=\"@wadewomersley\" \/>\n<meta name=\"twitter:site\" content=\"@wadewomersley\" \/>\n<meta name=\"twitter:label1\" content=\"Estimated reading time\" \/>\n\t<meta name=\"twitter:data1\" content=\"2 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\\\/\\\/schema.org\",\"@graph\":[{\"@type\":\"Article\",\"@id\":\"https:\\\/\\\/wade.one\\\/blog\\\/2026\\\/11\\\/16\\\/missing-and-null-need-different-rules-in-a-patch-api\\\/#article\",\"isPartOf\":{\"@id\":\"https:\\\/\\\/wade.one\\\/blog\\\/2026\\\/11\\\/16\\\/missing-and-null-need-different-rules-in-a-patch-api\\\/\"},\"author\":{\"name\":\"\",\"@id\":\"\"},\"headline\":\"Missing and Null Need Different Rules in a PATCH API\",\"datePublished\":\"2026-11-16T18:00:00+00:00\",\"mainEntityOfPage\":{\"@id\":\"https:\\\/\\\/wade.one\\\/blog\\\/2026\\\/11\\\/16\\\/missing-and-null-need-different-rules-in-a-patch-api\\\/\"},\"wordCount\":376,\"publisher\":{\"@id\":\"https:\\\/\\\/wade.one\\\/blog\\\/#\\\/schema\\\/person\\\/8b4739f8f8bb2cff5d792d4b8779fcc3\"},\"keywords\":[\"api\",\"json-merge-patch\",\"validation\"],\"articleSection\":[\"Programming\"],\"inLanguage\":\"en-GB\"},{\"@type\":\"WebPage\",\"@id\":\"https:\\\/\\\/wade.one\\\/blog\\\/2026\\\/11\\\/16\\\/missing-and-null-need-different-rules-in-a-patch-api\\\/\",\"url\":\"https:\\\/\\\/wade.one\\\/blog\\\/2026\\\/11\\\/16\\\/missing-and-null-need-different-rules-in-a-patch-api\\\/\",\"name\":\"Missing and Null Need Different Rules in a PATCH API - wade.one\",\"isPartOf\":{\"@id\":\"https:\\\/\\\/wade.one\\\/blog\\\/#website\"},\"datePublished\":\"2026-11-16T18:00:00+00:00\",\"breadcrumb\":{\"@id\":\"https:\\\/\\\/wade.one\\\/blog\\\/2026\\\/11\\\/16\\\/missing-and-null-need-different-rules-in-a-patch-api\\\/#breadcrumb\"},\"inLanguage\":\"en-GB\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\\\/\\\/wade.one\\\/blog\\\/2026\\\/11\\\/16\\\/missing-and-null-need-different-rules-in-a-patch-api\\\/\"]}]},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\\\/\\\/wade.one\\\/blog\\\/2026\\\/11\\\/16\\\/missing-and-null-need-different-rules-in-a-patch-api\\\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\\\/\\\/wade.one\\\/blog\\\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Missing and Null Need Different Rules in a PATCH API\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\\\/\\\/wade.one\\\/blog\\\/#website\",\"url\":\"https:\\\/\\\/wade.one\\\/blog\\\/\",\"name\":\"wade.one\",\"description\":\"wade womersley - york based software engineer\",\"publisher\":{\"@id\":\"https:\\\/\\\/wade.one\\\/blog\\\/#\\\/schema\\\/person\\\/8b4739f8f8bb2cff5d792d4b8779fcc3\"},\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\\\/\\\/wade.one\\\/blog\\\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"en-GB\"},{\"@type\":[\"Person\",\"Organization\"],\"@id\":\"https:\\\/\\\/wade.one\\\/blog\\\/#\\\/schema\\\/person\\\/8b4739f8f8bb2cff5d792d4b8779fcc3\",\"name\":\"Wade Womersley\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-GB\",\"@id\":\"https:\\\/\\\/wade.one\\\/blog\\\/wp-content\\\/uploads\\\/2015\\\/02\\\/200px.png\",\"url\":\"https:\\\/\\\/wade.one\\\/blog\\\/wp-content\\\/uploads\\\/2015\\\/02\\\/200px.png\",\"contentUrl\":\"https:\\\/\\\/wade.one\\\/blog\\\/wp-content\\\/uploads\\\/2015\\\/02\\\/200px.png\",\"width\":202,\"height\":200,\"caption\":\"Wade Womersley\"},\"logo\":{\"@id\":\"https:\\\/\\\/wade.one\\\/blog\\\/wp-content\\\/uploads\\\/2015\\\/02\\\/200px.png\"}}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"Missing and Null Need Different Rules in a PATCH API - wade.one","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/wade.one\/blog\/2026\/11\/16\/missing-and-null-need-different-rules-in-a-patch-api\/","og_locale":"en_GB","og_type":"article","og_title":"Missing and Null Need Different Rules in a PATCH API - wade.one","og_description":"Leaving a field out and deliberately clearing it are different requests. A partial-update endpoint needs to preserve that distinction.","og_url":"https:\/\/wade.one\/blog\/2026\/11\/16\/missing-and-null-need-different-rules-in-a-patch-api\/","og_site_name":"wade.one","article_published_time":"2026-11-16T18:00:00+00:00","og_image":[{"width":1518,"height":1506,"url":"https:\/\/wade.one\/blog\/wp-content\/uploads\/2015\/02\/Wade-Logo-cropped.png","type":"image\/png"}],"twitter_card":"summary_large_image","twitter_creator":"@wadewomersley","twitter_site":"@wadewomersley","twitter_misc":{"Estimated reading time":"2 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"Article","@id":"https:\/\/wade.one\/blog\/2026\/11\/16\/missing-and-null-need-different-rules-in-a-patch-api\/#article","isPartOf":{"@id":"https:\/\/wade.one\/blog\/2026\/11\/16\/missing-and-null-need-different-rules-in-a-patch-api\/"},"author":{"name":"","@id":""},"headline":"Missing and Null Need Different Rules in a PATCH API","datePublished":"2026-11-16T18:00:00+00:00","mainEntityOfPage":{"@id":"https:\/\/wade.one\/blog\/2026\/11\/16\/missing-and-null-need-different-rules-in-a-patch-api\/"},"wordCount":376,"publisher":{"@id":"https:\/\/wade.one\/blog\/#\/schema\/person\/8b4739f8f8bb2cff5d792d4b8779fcc3"},"keywords":["api","json-merge-patch","validation"],"articleSection":["Programming"],"inLanguage":"en-GB"},{"@type":"WebPage","@id":"https:\/\/wade.one\/blog\/2026\/11\/16\/missing-and-null-need-different-rules-in-a-patch-api\/","url":"https:\/\/wade.one\/blog\/2026\/11\/16\/missing-and-null-need-different-rules-in-a-patch-api\/","name":"Missing and Null Need Different Rules in a PATCH API - wade.one","isPartOf":{"@id":"https:\/\/wade.one\/blog\/#website"},"datePublished":"2026-11-16T18:00:00+00:00","breadcrumb":{"@id":"https:\/\/wade.one\/blog\/2026\/11\/16\/missing-and-null-need-different-rules-in-a-patch-api\/#breadcrumb"},"inLanguage":"en-GB","potentialAction":[{"@type":"ReadAction","target":["https:\/\/wade.one\/blog\/2026\/11\/16\/missing-and-null-need-different-rules-in-a-patch-api\/"]}]},{"@type":"BreadcrumbList","@id":"https:\/\/wade.one\/blog\/2026\/11\/16\/missing-and-null-need-different-rules-in-a-patch-api\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/wade.one\/blog\/"},{"@type":"ListItem","position":2,"name":"Missing and Null Need Different Rules in a PATCH API"}]},{"@type":"WebSite","@id":"https:\/\/wade.one\/blog\/#website","url":"https:\/\/wade.one\/blog\/","name":"wade.one","description":"wade womersley - york based software engineer","publisher":{"@id":"https:\/\/wade.one\/blog\/#\/schema\/person\/8b4739f8f8bb2cff5d792d4b8779fcc3"},"potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/wade.one\/blog\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"en-GB"},{"@type":["Person","Organization"],"@id":"https:\/\/wade.one\/blog\/#\/schema\/person\/8b4739f8f8bb2cff5d792d4b8779fcc3","name":"Wade Womersley","image":{"@type":"ImageObject","inLanguage":"en-GB","@id":"https:\/\/wade.one\/blog\/wp-content\/uploads\/2015\/02\/200px.png","url":"https:\/\/wade.one\/blog\/wp-content\/uploads\/2015\/02\/200px.png","contentUrl":"https:\/\/wade.one\/blog\/wp-content\/uploads\/2015\/02\/200px.png","width":202,"height":200,"caption":"Wade Womersley"},"logo":{"@id":"https:\/\/wade.one\/blog\/wp-content\/uploads\/2015\/02\/200px.png"}}]}},"jetpack_publicize_connections":[],"jetpack_sharing_enabled":true,"jetpack-related-posts":[{"id":1470,"url":"https:\/\/wade.one\/blog\/2026\/10\/27\/verify-webhook-signatures-before-parsing-away-the-evidence\/","url_meta":{"origin":1502,"position":0},"title":"Verify Webhook Signatures Before Parsing Away the Evidence","author":"","date":"October 27, 2026","format":false,"excerpt":"A webhook can contain perfectly sensible JSON and still fail signature verification.","rel":"","context":"In &quot;Programming&quot;","block_context":{"text":"Programming","link":"https:\/\/wade.one\/blog\/category\/programming\/"},"img":{"alt_text":"","src":"","width":0,"height":0},"classes":[]},{"id":764,"url":"https:\/\/wade.one\/blog\/2015\/02\/07\/standardising-logging-and-parallelisation-in-multiple-languages\/","url_meta":{"origin":1502,"position":1},"title":"Standardising logging and parallelisation in multiple languages","author":"Wade","date":"February 7, 2015","format":false,"excerpt":"Over the last few days I've been working on interfaces to use across multiple programming languages to standardise how some things are done. This stemmed from a requirement to allow processing to be dealt with in any language from any other language. People do this all the time, it's nothing\u2026","rel":"","context":"In &quot;Programming&quot;","block_context":{"text":"Programming","link":"https:\/\/wade.one\/blog\/category\/programming\/"},"img":{"alt_text":"","src":"https:\/\/i0.wp.com\/wade.one\/blog\/wp-content\/uploads\/2015\/02\/source-code-583537_640.jpg?resize=350%2C200&ssl=1","width":350,"height":200,"srcset":"https:\/\/i0.wp.com\/wade.one\/blog\/wp-content\/uploads\/2015\/02\/source-code-583537_640.jpg?resize=350%2C200&ssl=1 1x, https:\/\/i0.wp.com\/wade.one\/blog\/wp-content\/uploads\/2015\/02\/source-code-583537_640.jpg?resize=525%2C300&ssl=1 1.5x"},"classes":[]},{"id":1172,"url":"https:\/\/wade.one\/blog\/2026\/04\/05\/what-makes-an-api-feel-nice-to-work-with\/","url_meta":{"origin":1502,"position":2},"title":"What Makes an API Feel Nice to Work With","author":"","date":"April 5, 2026","format":false,"excerpt":"A good API is not just functional. It is predictable, consistent, and easy to use without a lot of guesswork.","rel":"","context":"In &quot;Programming&quot;","block_context":{"text":"Programming","link":"https:\/\/wade.one\/blog\/category\/programming\/"},"img":{"alt_text":"","src":"","width":0,"height":0},"classes":[]},{"id":1393,"url":"https:\/\/wade.one\/blog\/2026\/08\/14\/ai-coding-tools-need-the-same-policy-everywhere\/","url_meta":{"origin":1502,"position":3},"title":"AI Coding Tools Need the Same Policy Everywhere","author":"","date":"August 14, 2026","format":false,"excerpt":"Coding-agent governance only works when the same rules follow developers across every client and cloud task.","rel":"","context":"In &quot;Software Engineer&quot;","block_context":{"text":"Software Engineer","link":"https:\/\/wade.one\/blog\/category\/software-engineer\/"},"img":{"alt_text":"","src":"","width":0,"height":0},"classes":[]},{"id":1375,"url":"https:\/\/wade.one\/blog\/2026\/07\/14\/github-models-is-shutting-down-on-july-30\/","url_meta":{"origin":1502,"position":4},"title":"GitHub Models Is Shutting Down on July 30","author":"","date":"July 14, 2026","format":false,"excerpt":"GitHub Models closes on July 30, with brownouts first, so this is a migration deadline rather than a product update to read later.","rel":"","context":"In &quot;Software Engineer&quot;","block_context":{"text":"Software Engineer","link":"https:\/\/wade.one\/blog\/category\/software-engineer\/"},"img":{"alt_text":"","src":"","width":0,"height":0},"classes":[]},{"id":1184,"url":"https:\/\/wade.one\/blog\/2026\/04\/16\/how-i-decide-when-an-api-needs-versioning\/","url_meta":{"origin":1502,"position":5},"title":"How I Decide When an API Needs Versioning","author":"","date":"April 16, 2026","format":false,"excerpt":"API versioning is useful when the contract has really changed, not when a team wants a convenient place to hide messy changes. I usually want the compatibility story to be explicit before I reach for a new version.","rel":"","context":"In &quot;Programming&quot;","block_context":{"text":"Programming","link":"https:\/\/wade.one\/blog\/category\/programming\/"},"img":{"alt_text":"","src":"","width":0,"height":0},"classes":[]}],"jetpack_featured_media_url":"","_links":{"self":[{"href":"https:\/\/wade.one\/blog\/wp-json\/wp\/v2\/posts\/1502","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/wade.one\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/wade.one\/blog\/wp-json\/wp\/v2\/types\/post"}],"replies":[{"embeddable":true,"href":"https:\/\/wade.one\/blog\/wp-json\/wp\/v2\/comments?post=1502"}],"version-history":[{"count":2,"href":"https:\/\/wade.one\/blog\/wp-json\/wp\/v2\/posts\/1502\/revisions"}],"predecessor-version":[{"id":1523,"href":"https:\/\/wade.one\/blog\/wp-json\/wp\/v2\/posts\/1502\/revisions\/1523"}],"wp:attachment":[{"href":"https:\/\/wade.one\/blog\/wp-json\/wp\/v2\/media?parent=1502"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/wade.one\/blog\/wp-json\/wp\/v2\/categories?post=1502"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/wade.one\/blog\/wp-json\/wp\/v2\/tags?post=1502"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}