From 7542cf459789bbe6fcb9753688b45810a17d3648 Mon Sep 17 00:00:00 2001 From: Brandon Fowler Date: Sat, 22 Nov 2025 22:45:51 -0500 Subject: [PATCH] Document using `null` to reset values --- extending-the-rest-api/adding-custom-endpoints.md | 2 +- extending-the-rest-api/schema.md | 15 ++++++++++++++- 2 files changed, 15 insertions(+), 2 deletions(-) diff --git a/extending-the-rest-api/adding-custom-endpoints.md b/extending-the-rest-api/adding-custom-endpoints.md index 7ac3542..01956e3 100644 --- a/extending-the-rest-api/adding-custom-endpoints.md +++ b/extending-the-rest-api/adding-custom-endpoints.md @@ -120,7 +120,7 @@ Arguments are defined as a map in the key `args` for each endpoint (next to your * `default`: Used as the default value for the argument, if none is supplied. * `required`: If defined as true, and no value is passed for that argument, an error will be returned. No effect if a default value is set, as the argument will always have a value. -* `validate_callback`: Used to pass a function that will be passed the value of the argument. That function should return true if the value is valid, and false if not. +* `validate_callback`: Used to pass a function that will be passed the value of the argument. That function should return true if the value is valid, and false if not. Note that `null` values bypass validation. * `sanitize_callback`: Used to pass a function that is used to sanitize the value of the argument before passing it to the main callback. Using `sanitize_callback` and `validate_callback` allows the main callback to act only to process the request, and prepare data to be returned using the `WP_REST_Response` class. By using these two callbacks, you will be able to safely assume your inputs are valid and safe when processing. diff --git a/extending-the-rest-api/schema.md b/extending-the-rest-api/schema.md index 37471f5..a849689 100644 --- a/extending-the-rest-api/schema.md +++ b/extending-the-rest-api/schema.md @@ -362,7 +362,20 @@ Because the WordPress REST API accepts [URL form encoded](https://en.wikipedia.o When using multiple types, types will be evaluated in the order they are specified. This can have an impact on the sanitized data received by your REST API endpoint. For instance, in the previous example, if the value submitted was `"1"`, it would be sanitized to the boolean `true` value. However, if the order was flipped, the value would remain as the string `"1"`. -[info]The JSON Schema specification allows for defining schemas without a `type` field. The WordPress implementation however requires a `type` to be defined, and will issue a `_doing_it_wrong` notice if a type is ommitted.[/info] +[info]The JSON Schema specification allows for defining schemas without a `type` field. The WordPress implementation however requires a `type` to be defined, and will issue a `_doing_it_wrong` notice if a type is omitted.[/info] + +#### Resetting Values + +The WordPress REST API uses the value `null` (as in a properly typed `null` sent using JSON) to reset a value to the default for its type. This is accomplished by allowing parameters with a value of `null` to bypass validation. `null` is converted to the following values depending on the type: + +- `string` An empty string. +- `number` The value `0.0`. +- `integer` The value `0`. +- `boolean` The value `false`. +- `array` An empty native PHP array. +- `object` An empty native PHP array. + +When using multiple types, `null` will not be converted to any value by the sanitization function. ### Format