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.




git-svn-id: https://develop.svn.wordpress.org/trunk@62449 602fd350-edb4-49c9-b593-d223f7449a82

Author: gziolo

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

@@ -225,11 +225,20 @@ private function is_associative_array( $value ): bool {
 	/**
 	 * 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
 	 *
@@ -256,6 +265,40 @@ private function prepare_schema_for_response( array $schema ): array {
 
 		$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.
 		// Note: 'dependencies' values can also be property-dependency arrays
 		// (numeric arrays of strings) which are skipped via wp_is_numeric_array().

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

@@ -1505,6 +1505,31 @@ public function data_required_deeply_nested_property() {
 		);
 	}
 
+	/**
+	 * 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
 	 */