Validate and Sanitize WP REST API Request using WP JSON Schema?

Question

I'm currently setting up my first WP REST API and am attempting to understand how WP implements JSON Schema for the API endpoints, and the docs are imho really poor and confusing; so I wanted to make sure that I understand things properly:

1. According to this, you can specify the 'schema' parameter within the $args argument when registering a new rest route, to provide a JSON schema informing about the structure of the response of your endpoint. That schema should be delivered to any client making an OPTIONS HTTP request to the according endpoint. That works.

2. You can then specify any combination of the WP JSON Schema parameters for every parameter of your $args array when using register_rest_route, to inform about the required format of the request's arguments, for that respective endpoint. When I add for example a description key to the argument X of the endpoint Y, and then inspect the general https://example.org/wp-json/ REST schema of the website via GET, that description indeed shows up under the argument X of my API endpoint Y. So that also works.

3. What I totally don't understand is, how can I use the JSON schema I've specified in 2) for validation and subsequent (if validation is passed) sanitization? The docs mention the built-in rest_validate_value_from_schema and rest_validate_value_from_schema functions, but do not really show any examples / explain how you implement your JSON schemas provided for the request data (step 2)) for validation / sanitization.

How is that actually done using WP's built-in JSON schema ?

Answer 1

You're already providing a schema, the parameters in args are their own schemas, but WordPress does not enforce this schema or perform sanitisation/validation by default.

You can make WordPress enforce it though by setting the validation and sanitisation callbacks to the following:

'sanitize_callback' => 'rest_sanitize_request_arg',
'validate_callback' => 'rest_validate_request_arg',

rest_validate_request_arg will look up the parameter in the args and use that as the schema and pass it to rest_validate_value_from_schema for validation. The format of each parameter in the args section is also the format of the schema for that input because it is a schema.

For example, this is how WordPress defines validates and enforces the per_page parameter in the args section of collection endpoints:

            'per_page' => array(
                'description'       => __( 'Maximum number of items to be returned in result set.' ),
                'type'              => 'integer',
                'default'           => 10,
                'minimum'           => 1,
                'maximum'           => 100,
                'sanitize_callback' => 'absint',
                'validate_callback' => 'rest_validate_request_arg',
            ),

And here is how it does it internally:

function rest_validate_request_arg( $value, $request, $param ) {
    $attributes = $request->get_attributes();
    if ( ! isset( $attributes['args'][ $param ] ) || ! is_array( $attributes['args'][ $param ] ) ) {
        return true;
    }
    $args = $attributes['args'][ $param ];
 
    return rest_validate_value_from_schema( $value, $args, $param );
}

There is also a rest_sanitize_request_arg for sanitisation, but this is used in fewer locations in core itself.

• https://developer.wordpress.org/reference/functions/rest_sanitize_request_arg/
• https://developer.wordpress.org/reference/functions/rest_validate_request_arg/
• https://github.com/WordPress/WordPress/blob/c7d3e267b8a7aebc28b23efa74b2971602852315/wp-includes/rest-api/endpoints/class-wp-rest-controller.php#L348

Answer 2

So the way to do what's mentioned can be reached by the following, coded in your main plugin file or the active theme's functions.php. But as you see, I need to specify the JSON schema used for validation, sanitization, and request argument documentation. I just would like to know if there's a way to provide that schema only once and use it everywhere (of course in a way different from just storing it in a variable).

add_action(
                'rest_api_init',
                function () {
                    
                    // Register Route - START
                    
                    register_rest_route(
                        'api/v1',
                        '/zoo',
                        [
                            [
                                'methods'             => 'POST',
                                'permission_callback' => function ( WP_REST_Request $request ) { // authenticate client + check nonce
                                },
                                'callback'            => 'controller_callback',
                                'args'                => [
                                    'animal' => [
                                        'type' => 'string',
                                        'oneOf' => ['lion','tiger'],
                                        'description' => "string determining the kind of animal you're trying to create",
                                        'required'          => true,
                                        'validate_callback' => function ( $param ) {
                                            return rest_validate_value_from_schema( $param, ['type' => 'string', 'enum' => ['lion','tiger']]);
                                        },
                                        'sanitize_callback' => function ( $param ) {
                                            return rest_sanitize_value_from_schema( $param, ['type' => 'string', 'enum' => ['lion','tiger']]);
                                        }
                                    ],
                                    '_wpnonce' => [
                                        'required' => true
                                    ]
                                ]
                            ],
                            'schema' => function() { return array(
                                // This tells the spec of JSON Schema we are using which is draft 4.
                                '$schema'              => 'http://json-schema.org/draft-04/schema#',
                                // The title property marks the identity of the resource.
                                'title'                => 'animal',
                                'type'                 => 'object',
                                // In JSON Schema you can specify object properties in the properties attribute.
                                'properties'           => array(
                                    'id' => array(
                                        'description'  => 'ID of the created animal',
                                        'type'         => 'integer',
                                        'readonly'     => true,
                                    ),
                                    'animal' => array(
                                        'description'  => 'identifier of the animal type',
                                        'type'         => 'string',
                                    )
                                )); }
                        ]
                    );
    
                    // Register Route - END
                }
            );

Answer 3

So the finally correct (and tested) way to implement what I was looking for is:

add_action(
                'rest_api_init',
                function () {
                    
                    // Register Route - START
                    
                    register_rest_route(
                        'api/v1',
                        '/zoo',
                        [
                            [
                                'methods'             => 'POST',
                                'permission_callback' => function ( WP_REST_Request $request ) { // authenticate client + check nonce
                                },
                                'callback'            => 'controller_callback',
                                'args'                => [
                                    'animal' => [
                                        'type' => 'string',
                                        'enum' => ['lion','tiger'],
                                        'description' => "string determining the kind of animal you're trying to create",
                                        'required'          => true,
                                        'validate_callback' => 'rest_validate_request_arg',
                                        'sanitize_callback' => 'rest_sanitize_request_arg'
                                    ],
                                    '_wpnonce' => [
                                        'required' => true
                                    ]
                                ]
                            ]
                        ]
                    );
    
                    // Register Route - END
                }
            );

As a side-note, be aware that using JSON schema arguments exposes your argument validation + sanitization criteria through your endpoints, and will cause default responses with clear details about where your validation / sanitization failed.

This is perfect for development environments, but if you do not want this to happen in production environments, you're better off using custom validation and sanitization callbacks, where you can explicitly determine the information returned to your client in case of any failure, as documented here.

Was just a final thought I had on this story.