Changeset 62549

Timestamp:

06/23/2026 11:40:49 AM (4 months ago)

Author:

gziolo

Message:

REST API: Add a shared helper for JSON Schema allowed keywords.

Introduce wp_get_json_schema_allowed_keywords() as the single place to decide which JSON Schema keywords may stay in schema output. It supports two profiles: rest-api (the default, used for REST route output) and draft-04 (a wider draft-04 set used when publishing schemas to clients such as the Abilities API).

Route schema output now flows through the helper and the new wp_json_schema_allowed_keywords filter, replacing the Abilities-specific special casing in the REST list controller. Validation internals still call rest_get_allowed_schema_keywords() directly, so REST validation behavior does not change.

Props gziolo, apermo.
See #64955.

Location:

trunk

Files:

• src/wp-includes/json-schema.php (added)
• src/wp-includes/rest-api/class-wp-rest-server.php (modified) (1 diff)
• src/wp-includes/rest-api/endpoints/class-wp-rest-abilities-v1-list-controller.php (modified) (4 diffs)
• src/wp-settings.php (modified) (1 diff)
• tests/phpunit/tests/abilities-api/wpRegisterCoreAbilities.php (modified) (1 diff)
• tests/phpunit/tests/json-schema.php (added)
• tests/phpunit/tests/rest-api/rest-server.php (modified) (1 diff)

trunk/src/wp-includes/rest-api/class-wp-rest-server.php

@@ -1650 +1650 @@
                 }
 
-                $allowed_schema_keywords = array_flip( rest_get_allowed_schema_keywords() );
+                $allowed_schema_keywords = array_flip( wp_get_json_schema_allowed_keywords( 'rest-api' ) );
 
                 $route = preg_replace( '#\(\?P<(\w+?)>.*?\)#', '{$1}', $route );

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

@@ -34 +34 @@
          */
         protected $rest_base = 'abilities';
+
+        /**
+         * Lookup map of allowed schema keywords for preparing ability schemas in REST responses.
+         *
+         * Keyword names are stored as keys so they can be matched with
+         * array_intersect_key(). Computed lazily on first use and reused while
+         * preparing nested schemas.
+         *
+         * @since 7.1.0
+         * @var array<string, true>
+         */
+        private array $allowed_schema_keyword_lookup;
 
         /**
@@ -195 +207 @@
 
         /**
-         * Additional schema keywords to preserve in REST responses.
-         *
-         * Ability schemas are exposed to clients as JSON Schema. Preserve additional
-         * draft-04 keywords so clients can validate richer schemas, even when some
-         * of those keywords are not enforced by the server-side REST schema validator.
-         *
-         * @since 7.1.0
-         * @var string[]
-         */
-        private const ADDITIONAL_ALLOWED_SCHEMA_KEYWORDS = array(
-                'required',
-                'allOf',
-                'not',
-                '$ref',
-                'definitions',
-                'dependencies',
-                'additionalItems',
-        );
-
-        /**
          * Determines whether the value is an associative array.
          *
@@ -226 +218 @@
         private function is_associative_array( $value ): bool {
                 return is_array( $value ) && ! wp_is_numeric_array( $value );
+        }
+
+        /**
+         * Gets the allowed schema keywords for preparing ability schemas in REST responses.
+         *
+         * Uses the fuller draft-04 keyword set, not the smaller REST API subset.
+         * The published schema is consumed by clients that re-validate values
+         * against standard draft-04, so it keeps the keywords those validators
+         * expect.
+         *
+         * @since 7.1.0
+         *
+         * @return array<string, true> Allowed schema keywords.
+         */
+        private function get_allowed_schema_keywords_for_response(): array {
+                if ( ! isset( $this->allowed_schema_keyword_lookup ) ) {
+                        $this->allowed_schema_keyword_lookup = array_fill_keys( wp_get_json_schema_allowed_keywords( 'draft-04' ), true );
+                }
+
+                return $this->allowed_schema_keyword_lookup;
         }
 
@@ -259 +271 @@
                 }
 
-                // Computed once and reused across the recursive calls for every schema node.
-                static $allowed_keywords = null;
-                $allowed_keywords      ??= array_fill_keys(
-                        array_merge(
-                                rest_get_allowed_schema_keywords(),
-                                self::ADDITIONAL_ALLOWED_SCHEMA_KEYWORDS
-                        ),
-                        true
-                );
-
-                $schema = array_intersect_key( $schema, $allowed_keywords );
+                $schema = array_intersect_key( $schema, $this->get_allowed_schema_keywords_for_response() );
 
                 // Collect draft-03 per-property `required: true` flags into a draft-04

trunk/src/wp-settings.php

@@ -314 +314 @@
 require ABSPATH . WPINC . '/abilities.php';
 require ABSPATH . WPINC . '/rest-api.php';
+require ABSPATH . WPINC . '/json-schema.php';
 require ABSPATH . WPINC . '/rest-api/class-wp-rest-server.php';
 require ABSPATH . WPINC . '/rest-api/class-wp-rest-response.php';

trunk/tests/phpunit/tests/abilities-api/wpRegisterCoreAbilities.php

@@ -386 +386 @@
          */
         public function test_core_abilities_schemas_use_only_valid_keywords(): void {
-                $allowed_keywords = rest_get_allowed_schema_keywords();
-                // Add 'required' which is valid at the property level for draft-04.
-                $allowed_keywords[] = 'required';
+                $allowed_keywords = wp_get_json_schema_allowed_keywords( 'draft-04' );
 
                 $abilities = wp_get_abilities();

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

@@ -2521 +2521 @@
 
         /**
+         * @ticket 64955
+         */
+        public function test_get_data_for_route_includes_filtered_json_schema_keywords() {
+                $filter = static function ( $keywords, $schema_profile ) {
+                        if ( 'rest-api' === $schema_profile ) {
+                                $keywords[] = 'xRestApiKeyword';
+                        }
+
+                        return $keywords;
+                };
+
+                add_filter( 'wp_json_schema_allowed_keywords', $filter, 10, 2 );
+
+                register_rest_route(
+                        'test-ns/v1',
+                        '/test',
+                        array(
+                                'methods'             => 'POST',
+                                'callback'            => static function () {
+                                        return new WP_REST_Response( 'test' );
+                                },
+                                'permission_callback' => '__return_true',
+                                'args'                => array(
+                                        'param' => array(
+                                                'type'            => 'string',
+                                                'xRestApiKeyword' => true,
+                                                'invalid'         => true,
+                                        ),
+                                ),
+                        )
+                );
+
+                $response = rest_do_request( new WP_REST_Request( 'OPTIONS', '/test-ns/v1/test' ) );
+
+                $args = $response->get_data()['endpoints'][0]['args'];
+
+                $this->assertArrayHasKey( 'xRestApiKeyword', $args['param'] );
+                $this->assertArrayNotHasKey( 'invalid', $args['param'] );
+        }
+
+        /**
          * @ticket 53056
          */