Context Navigation

← Previous Changeset
Next Changeset →

Changeset 62449

Timestamp:

06/02/2026 02:08:49 PM (6 weeks ago)

Author:

gziolo

Message:

Abilities API: Normalize required schema shape for REST responses

Ability schemas are a public contract that REST clients, including the @wordpress/abilities JavaScript client, validate against as standard JSON Schema. The required keyword must therefore use the draft-04 array-of-property-names form, not the draft-03 per-property boolean that rest_validate_value_from_schema() also accepts on the server.

In WP_REST_Abilities_V1_List_Controller::prepare_schema_for_response(), collect per-property required: true booleans into a parent required array, recursively and inside array items. Strip required: false and boolean required values with no draft-04 equivalent, and honor rest_validate_object_value_from_schema() precedence where an existing draft-04 array wins. Only the REST response copy is rewritten; stored schemas and server-side validation are unchanged.

Props gziolo, westonruter, jorgefilipecosta.
See #64955.

Location:

trunk

Files:

: 3 edited

src/wp-includes/rest-api/endpoints/class-wp-rest-abilities-v1-list-controller.php (modified) (2 diffs)
tests/phpunit/tests/rest-api/rest-schema-validation.php (modified) (1 diff)
tests/phpunit/tests/rest-api/wpRestAbilitiesV1ListController.php (modified) (1 diff)

Legend:

: Unmodified
: Added
: Removed

trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-abilities-v1-list-controller.php

-              r62447
+              r62449
          * Transforms an ability schema for REST response output.
+         *
+         * The input and output schemas are a public contract: REST clients (such as
+         * the `@wordpress/abilities` JS client) consume them as standard JSON Schema
+         * and validate ability input and output against them. The response must
+         * therefore use JSON Schema draft-04 forms that standard validators
+         * understand, not the WordPress-internal conventions that
+         * `rest_validate_value_from_schema()` also accepts on the server.
+         *
          * Ability schemas may include WordPress-internal properties or unsupported
          * schema keywords that should not be exposed in REST responses. This method
          * strips keys not recognized by the REST API schema handling. It also
          * converts empty array defaults to objects when the schema type is 'object'
+         * to ensure proper JSON serialization as {} instead of [].
+         * to ensure proper JSON serialization as {} instead of [], and normalizes
+         * the `required` keyword from the draft-03 per-property boolean form into
+         * the draft-04 array of property names.
+         *
          * @since 7.1.0
 …
                 $schema = array_intersect_key( $schema, $allowed_keywords );
+                // Collect draft-03 per-property `required: true` flags into a draft-04
+                // `required` array of property names on the parent object schema.
+                //
+                // This mirrors rest_validate_object_value_from_schema(), where a draft-04
+                // `required` array takes precedence: when one is present, per-property
+                // booleans are ignored during validation. They are therefore left out of
+                // the array here as well (but still stripped from the output) so the
+                // published schema describes exactly what gets enforced.
+                if ( isset( $schema['properties'] ) && is_array( $schema['properties'] ) ) {
+                        $has_required_array = isset( $schema['required'] ) && is_array( $schema['required'] );
+                        $required           = array();
+                        foreach ( $schema['properties'] as $property => &$property_schema ) {
+                                if ( $this->is_associative_array( $property_schema ) && isset( $property_schema['required'] ) && is_bool( $property_schema['required'] ) ) {
+                                        if ( ! $has_required_array && true === $property_schema['required'] ) {
+                                                $required[] = (string) $property;
+                                        }
+                                        unset( $property_schema['required'] );
+                                }
+                        }
+                        unset( $property_schema );
+                        // Property keys are unique, so the collected list needs no deduplication.
+                        // When a draft-04 array is already present, leave it untouched.
+                        if ( ! $has_required_array && count( $required ) > 0 ) {
+                                $schema['required'] = $required;
+                        }
+                }
+                // A boolean `required` outside of an object's property list has no draft-04
+                // equivalent, so drop it rather than emit an invalid keyword.
+                if ( isset( $schema['required'] ) && is_bool( $schema['required'] ) ) {
+                        unset( $schema['required'] );
+                }
                 // Sub-schema maps: keys are user-defined, values are sub-schemas.

trunk/tests/phpunit/tests/rest-api/rest-schema-validation.php

-              r59040
+              r62449
         /**
+         * A draft-04 `required` array takes precedence over per-property
+         * `required` booleans on the same object node: the booleans are ignored.
+         *
+         * @ticket 64955
+         */
+        public function test_required_v4_array_takes_precedence_over_v3_booleans() {
+                $schema = array(
+                        'type'       => 'object',
+                        'required'   => array( 'listed' ),
+                        'properties' => array(
+                                'listed'  => array( 'type' => 'string' ),
+                                'flagged' => array(
+                                        'type'     => 'string',
+                                        'required' => true, // Ignored because the array is present.
+                                ),
+                        ),
+                );
+                // Missing the array-listed prop fails.
+                $this->assertWPError( rest_validate_value_from_schema( array( 'flagged' => 'x' ), $schema ) );
+                // Missing only the boolean-flagged prop passes — the boolean is not enforced.
+                $this->assertTrue( rest_validate_value_from_schema( array( 'listed' => 'x' ), $schema ) );
+        }
+        /**
          * @ticket 51023
          */

trunk/tests/phpunit/tests/rest-api/wpRestAbilitiesV1ListController.php

-              r62447
+              r62449
                 $this->assertSame( 'boolean', $data['output_schema']['additionalItems']['type'] );
+        }
+        /**
+         * Test that per-property `required` booleans become a draft-04 `required` array.
+         *
+         * @ticket 64955
+         */
+        public function test_required_property_booleans_converted_to_draft_04_array(): void {
+                $this->register_test_ability(
+                        'test/required-booleans',
+                        array(
+                                'label'               => 'Required Booleans',
+                                'description'         => 'Tests conversion of per-property required booleans.',
+                                'category'            => 'general',
+                                'input_schema'        => array(
+                                        'type'       => 'object',
+                                        'properties' => array(
+                                                'title'    => array(
+                                                        'type'     => 'string',
+                                                        'required' => true,
+                                                ),
+                                                'content'  => array(
+                                                        'type'     => 'string',
+                                                        'required' => true,
+                                                ),
+                                                'optional' => array(
+                                                        'type' => 'string',
+                                                ),
+                                        ),
+                                ),
+                                'output_schema'       => array(
+                                        'type'       => 'object',
+                                        'properties' => array(
+                                                'id' => array(
+                                                        'type'     => 'integer',
+                                                        'required' => true,
+                                                ),
+                                        ),
+                                ),
+                                'execute_callback'    => static function (): array {
+                                        return array( 'id' => 1 );
+                                },
+                                'permission_callback' => '__return_true',
+                                'meta'                => array( 'show_in_rest' => true ),
+                        )
+                );
+                $request  = new WP_REST_Request( 'GET', '/wp-abilities/v1/abilities/test/required-booleans' );
+                $response = $this->server->dispatch( $request );
+                $this->assertSame( 200, $response->get_status() );
+                $data = $response->get_data();
+                // The `required` array lists the names of the properties flagged as required.
+                $this->assertArrayHasKey( 'required', $data['input_schema'] );
+                $this->assertSameSets( array( 'title', 'content' ), $data['input_schema']['required'] );
+                // The boolean flag is removed from each property sub-schema.
+                $this->assertArrayNotHasKey( 'required', $data['input_schema']['properties']['title'] );
+                $this->assertArrayNotHasKey( 'required', $data['input_schema']['properties']['content'] );
+                $this->assertArrayNotHasKey( 'required', $data['input_schema']['properties']['optional'] );
+                // Output schemas are normalized the same way.
+                $this->assertSame( array( 'id' ), $data['output_schema']['required'] );
+                $this->assertArrayNotHasKey( 'required', $data['output_schema']['properties']['id'] );
+        }
+        /**
+         * Test that per-property `required` booleans are converted in nested object schemas.
+         *
+         * @ticket 64955
+         */
+        public function test_required_booleans_converted_in_nested_object_schemas(): void {
+                $this->register_test_ability(
+                        'test/required-nested',
+                        array(
+                                'label'               => 'Required Nested',
+                                'description'         => 'Tests conversion within nested object schemas.',
+                                'category'            => 'general',
+                                'input_schema'        => array(
+                                        'type'       => 'object',
+                                        'properties' => array(
+                                                'address' => array(
+                                                        'type'       => 'object',
+                                                        'required'   => true,
+                                                        'properties' => array(
+                                                                'street' => array(
+                                                                        'type'     => 'string',
+                                                                        'required' => true,
+                                                                ),
+                                                                'city'   => array(
+                                                                        'type' => 'string',
+                                                                ),
+                                                        ),
+                                                ),
+                                        ),
+                                ),
+                                'execute_callback'    => static function () {
+                                        return null;
+                                },
+                                'permission_callback' => '__return_true',
+                                'meta'                => array( 'show_in_rest' => true ),
+                        )
+                );
+                $request  = new WP_REST_Request( 'GET', '/wp-abilities/v1/abilities/test/required-nested' );
+                $response = $this->server->dispatch( $request );
+                $this->assertSame( 200, $response->get_status() );
+                $data    = $response->get_data();
+                $address = $data['input_schema']['properties']['address'];
+                // The outer object lists the nested object as a required property.
+                $this->assertSame( array( 'address' ), $data['input_schema']['required'] );
+                // The nested object's own boolean flag is replaced by a draft-04 array
+                // collecting its own required properties (proving the boolean was converted).
+                $this->assertSame( array( 'street' ), $address['required'] );
+                $this->assertArrayNotHasKey( 'required', $address['properties']['street'] );
+                $this->assertArrayNotHasKey( 'required', $address['properties']['city'] );
+        }
+        /**
+         * Test that `required: false` is removed without emitting an empty `required` array.
+         *
+         * @ticket 64955
+         */
+        public function test_required_false_booleans_removed_without_required_array(): void {
+                $this->register_test_ability(
+                        'test/required-false',
+                        array(
+                                'label'               => 'Required False',
+                                'description'         => 'Tests that required:false is stripped.',
+                                'category'            => 'general',
+                                'input_schema'        => array(
+                                        'type'       => 'object',
+                                        'properties' => array(
+                                                'maybe' => array(
+                                                        'type'     => 'string',
+                                                        'required' => false,
+                                                ),
+                                        ),
+                                ),
+                                'execute_callback'    => static function () {
+                                        return null;
+                                },
+                                'permission_callback' => '__return_true',
+                                'meta'                => array( 'show_in_rest' => true ),
+                        )
+                );
+                $request  = new WP_REST_Request( 'GET', '/wp-abilities/v1/abilities/test/required-false' );
+                $response = $this->server->dispatch( $request );
+                $this->assertSame( 200, $response->get_status() );
+                $data = $response->get_data();
+                $this->assertArrayNotHasKey( 'required', $data['input_schema'] );
+                $this->assertArrayNotHasKey( 'required', $data['input_schema']['properties']['maybe'] );
+        }
+        /**
+         * Test that an existing draft-04 `required` array takes precedence over per-property booleans.
+         *
+         * This mirrors rest_validate_object_value_from_schema(), which ignores
+         * per-property `required` booleans when a draft-04 `required` array is
+         * present, so the published schema matches what is actually enforced.
+         *
+         * @ticket 64955
+         */
+        public function test_required_draft_04_array_takes_precedence_over_booleans(): void {
+                $this->register_test_ability(
+                        'test/required-mixed',
+                        array(
+                                'label'               => 'Required Mixed',
+                                'description'         => 'Tests precedence of a draft-04 array over draft-03 booleans.',
+                                'category'            => 'general',
+                                'input_schema'        => array(
+                                        'type'       => 'object',
+                                        'required'   => array( 'title' ),
+                                        'properties' => array(
+                                                'title'   => array(
+                                                        'type'     => 'string',
+                                                        'required' => true,
+                                                ),
+                                                'content' => array(
+                                                        'type'     => 'string',
+                                                        'required' => true,
+                                                ),
+                                        ),
+                                ),
+                                'execute_callback'    => static function () {
+                                        return null;
+                                },
+                                'permission_callback' => '__return_true',
+                                'meta'                => array( 'show_in_rest' => true ),
+                        )
+                );
+                $request  = new WP_REST_Request( 'GET', '/wp-abilities/v1/abilities/test/required-mixed' );
+                $response = $this->server->dispatch( $request );
+                $this->assertSame( 200, $response->get_status() );
+                $data = $response->get_data();
+                // The draft-04 array wins: the `content` boolean is ignored, not merged in.
+                $this->assertSame( array( 'title' ), $data['input_schema']['required'] );
+                // The per-property booleans are still stripped from the output.
+                $this->assertArrayNotHasKey( 'required', $data['input_schema']['properties']['title'] );
+                $this->assertArrayNotHasKey( 'required', $data['input_schema']['properties']['content'] );
+        }
+        /**
+         * Test that a boolean `required` with no draft-04 equivalent (e.g. on a scalar) is dropped.
+         *
+         * @ticket 64955
+         */
+        public function test_required_boolean_on_scalar_schema_removed(): void {
+                $this->register_test_ability(
+                        'test/required-scalar',
+                        array(
+                                'label'               => 'Required Scalar',
+                                'description'         => 'Tests stripping of a boolean required on a scalar schema.',
+                                'category'            => 'general',
+                                'input_schema'        => array(
+                                        'type'        => 'string',
+                                        'description' => 'The text to analyze.',
+                                        'required'    => true,
+                                ),
+                                'output_schema'       => array(
+                                        'type'     => 'string',
+                                        'required' => true,
+                                ),
+                                'execute_callback'    => static function ( $input ) {
+                                        return $input;
+                                },
+                                'permission_callback' => '__return_true',
+                                'meta'                => array( 'show_in_rest' => true ),
+                        )
+                );
+                $request  = new WP_REST_Request( 'GET', '/wp-abilities/v1/abilities/test/required-scalar' );
+                $response = $this->server->dispatch( $request );
+                $this->assertSame( 200, $response->get_status() );
+                $data = $response->get_data();
+                $this->assertArrayNotHasKey( 'required', $data['input_schema'] );
+                $this->assertSame( 'string', $data['input_schema']['type'] );
+                $this->assertArrayNotHasKey( 'required', $data['output_schema'] );
+        }
+        /**
+         * Test that per-property `required` booleans are converted in an array's `items` object.
+         *
+         * @ticket 64955
+         */
+        public function test_required_booleans_converted_in_array_items_object_schemas(): void {
+                $this->register_test_ability(
+                        'test/required-array-items',
+                        array(
+                                'label'               => 'Required Array Items',
+                                'description'         => 'Tests conversion within array item object schemas.',
+                                'category'            => 'general',
+                                'input_schema'        => array(
+                                        'type'  => 'array',
+                                        'items' => array(
+                                                'type'       => 'object',
+                                                'properties' => array(
+                                                        'id'    => array(
+                                                                'type'     => 'integer',
+                                                                'required' => true,
+                                                        ),
+                                                        'label' => array(
+                                                                'type' => 'string',
+                                                        ),
+                                                ),
+                                        ),
+                                ),
+                                'execute_callback'    => static function () {
+                                        return null;
+                                },
+                                'permission_callback' => '__return_true',
+                                'meta'                => array( 'show_in_rest' => true ),
+                        )
+                );
+                $request  = new WP_REST_Request( 'GET', '/wp-abilities/v1/abilities/test/required-array-items' );
+                $response = $this->server->dispatch( $request );
+                $this->assertSame( 200, $response->get_status() );
+                $data  = $response->get_data();
+                $items = $data['input_schema']['items'];
+                // The object schema inside `items` collects its own required properties
+                // into a draft-04 array, and the per-property boolean is removed.
+                $this->assertSame( array( 'id' ), $items['required'] );
+                $this->assertArrayNotHasKey( 'required', $items['properties']['id'] );
+                $this->assertArrayNotHasKey( 'required', $items['properties']['label'] );
+        }
+}

Note: See TracChangeset for help on using the changeset viewer.

Make WordPress Core