Commit 22e95b37de6 for woocommerce

commit 22e95b37de65a26f15647ecacaa8b9642c0dca76
Author: Luis Felipe Zaguini <26530524+zaguiini@users.noreply.github.com>
Date:   Thu Nov 19 11:05:09 2026 -0300

    Refuse nested lists of types in extension field schemas (#71083)

    * Document that nested output properties of extension fields must not be nullable

    Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

    * Refuse nullable nested types in extension field schemas

    Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

    * Check patternProperties and allOf for nullable nested types

    Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

    * Name the schema keywords that the nested type check walks

    Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

    * Refuse only nested lists of types, and allow nested null branches in output schemas

    Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

    ---------

    Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

diff --git a/plugins/woocommerce/changelog/update-extensible-abilities-nested-output-docs b/plugins/woocommerce/changelog/update-extensible-abilities-nested-output-docs
new file mode 100644
index 00000000000..8b58803acd8
--- /dev/null
+++ b/plugins/woocommerce/changelog/update-extensible-abilities-nested-output-docs
@@ -0,0 +1,3 @@
+Significance: patch
+Type: dev
+Comment: Refuse nested lists of types in extension field schemas of the experimental extensible abilities; not stable yet.
diff --git a/plugins/woocommerce/src/Abilities/ExtensibleAbilities.php b/plugins/woocommerce/src/Abilities/ExtensibleAbilities.php
index d6232c65819..925ba1ad4f2 100644
--- a/plugins/woocommerce/src/Abilities/ExtensibleAbilities.php
+++ b/plugins/woocommerce/src/Abilities/ExtensibleAbilities.php
@@ -135,7 +135,14 @@ class ExtensibleAbilities {
 	 *     @type array    $output_schema Optional. JSON schema of the value that `get_callback` returns. Required
 	 *                                  with `get_callback`. It needs one `type` other than null, because clients
 	 *                                  expect one type for each field. Core publishes it as declared. Its
-	 *                                  `title` is the label clients show.
+	 *                                  `title` is the label clients show. Leave a nested property out when it has
+	 *                                  no value. Where a nested value must be null, such as an item of a list,
+	 *                                  declare it with an `anyOf` that has a `{"type":"null"}` branch. A list of
+	 *                                  types is refused in every nested schema under `properties`,
+	 *                                  `patternProperties`, `additionalProperties`, `items`, `anyOf` and `oneOf`,
+	 *                                  which are the keywords with a nested schema that WordPress supports (see
+	 *                                  `rest_get_allowed_schema_keywords()`), and under `allOf`, which
+	 *                                  WooCommerce also reads, because some clients refuse it.
 	 *     @type string[] $object_types Optional. The object types the field applies to, as `get_type()` of the
 	 *                                  object returns them, such as `simple` and `subscription` for a product or
 	 *                                  `line_item` for an order item. The object must have a `get_type()` method.
@@ -154,8 +161,9 @@ class ExtensibleAbilities {
 	 *                                  the whole result.
 	 *     @type array    $input_schema Optional. JSON schema of the value that `set_callback` receives. It needs
 	 *                                  one `type` name, or an `anyOf` where each branch has one `type` name. A
-	 *                                  list of types is refused at the top level, because some clients refuse it:
-	 *                                  a nullable field uses `[{"type":"string"},{"type":"null"}]` as its `anyOf`.
+	 *                                  list of types is refused, at the top level and in every nested schema under
+	 *                                  the keywords listed for `output_schema`, because some clients refuse it: a
+	 *                                  nullable value uses `[{"type":"string"},{"type":"null"}]` as its `anyOf`.
 	 *                                  Core publishes it as declared. A value can be null only where it declares
 	 *                                  null. Required with `set_callback`.
 	 *     @type callable $set_callback Optional. Receives the object and the value, and changes the object
@@ -239,6 +247,13 @@ class ExtensibleAbilities {
 				return;
 			}
 		}
+		foreach ( array( 'output_schema', 'input_schema' ) as $key ) {
+			$path = isset( $args[ $key ] ) ? self::find_nested_type_list( $args[ $key ] ) : null;
+			if ( null !== $path ) {
+				wc_doing_it_wrong( __METHOD__, sprintf( 'The "%1$s" argument has a list of types at "%2$s". Use an "anyOf" with a {"type":"null"} branch instead. In an output, prefer to leave the property out when it has no value.', $key, $path ), '11.4.0' );
+				return;
+			}
+		}
 		if ( isset( $args['object_types'] ) && ( ! is_array( $args['object_types'] ) || empty( $args['object_types'] ) || array_filter( $args['object_types'], static fn( $type ) => ! is_string( $type ) ) ) ) {
 			wc_doing_it_wrong( __METHOD__, 'The "object_types" argument must be a list of object types.', '11.4.0' );
 			return;
@@ -284,6 +299,40 @@ class ExtensibleAbilities {
 		return true;
 	}

+	/**
+	 * Find the first nested schema under `properties`, `patternProperties`, `additionalProperties`, `items`,
+	 * `anyOf`, `oneOf` or `allOf` whose `type` is a list.
+	 *
+	 * @param array<string, mixed> $schema Field schema.
+	 * @param string               $path   Path of the schema, such as `properties.size`.
+	 * @return string|null Path of the first schema with a list of types, or null when there is none.
+	 */
+	private static function find_nested_type_list( array $schema, string $path = '' ): ?string {
+		foreach ( array( 'properties', 'patternProperties', 'additionalProperties', 'items', 'anyOf', 'oneOf', 'allOf' ) as $keyword ) {
+			$children = $schema[ $keyword ] ?? null;
+			if ( ! is_array( $children ) ) {
+				continue;
+			}
+			if ( 'additionalProperties' === $keyword || ( 'items' === $keyword && ! wp_is_numeric_array( $children ) ) ) {
+				$children = array( '' => $children );
+			}
+			foreach ( $children as $key => $child ) {
+				if ( ! is_array( $child ) ) {
+					continue;
+				}
+				$child_path = trim( "$path.$keyword.$key", '.' );
+				if ( is_array( $child['type'] ?? null ) ) {
+					return $child_path;
+				}
+				$found = self::find_nested_type_list( $child, $child_path );
+				if ( null !== $found ) {
+					return $found;
+				}
+			}
+		}
+		return null;
+	}
+
 	/**
 	 * Register a filter that the list ability of a resource accepts under `filters.extensions.<namespace>.<filter>`.
 	 *
diff --git a/plugins/woocommerce/tests/php/src/Internal/AbilitiesApi/ExtensibleAbilitiesTest.php b/plugins/woocommerce/tests/php/src/Internal/AbilitiesApi/ExtensibleAbilitiesTest.php
index fcc28d743ec..6e8a8a62e0e 100644
--- a/plugins/woocommerce/tests/php/src/Internal/AbilitiesApi/ExtensibleAbilitiesTest.php
+++ b/plugins/woocommerce/tests/php/src/Internal/AbilitiesApi/ExtensibleAbilitiesTest.php
@@ -1405,10 +1405,207 @@ class ExtensibleAbilitiesTest extends \WC_REST_Unit_Test_Case {
 		$this->assertArrayNotHasKey( 'refused', ExtensibleAbilities::get_fields( 'order' ) );
 	}

+	/**
+	 * @testdox Should refuse a field whose output schema has a list of types below the top level.
+	 * @dataProvider provider_nested_type_list_output_schemas
+	 * @param array $schema Output schema.
+	 */
+	public function test_a_nested_type_list_in_an_output_schema_is_refused( array $schema ): void {
+		$this->setExpectedIncorrectUsage( ExtensibleAbilities::class . '::register_field' );
+		AbilitiesLoader::register_core_resources();
+
+		ExtensibleAbilities::register_field(
+			array(
+				'resource'      => 'order',
+				'namespace'     => 'refused',
+				'field'         => 'value',
+				'output_schema' => $schema,
+				'get_callback'  => '__return_null',
+			)
+		);
+
+		$this->assertArrayNotHasKey( 'refused', ExtensibleAbilities::get_fields( 'order' ) );
+	}
+
+	/**
+	 * Output schemas with a list of types below the top level.
+	 *
+	 * @return array<string, array{0: array<string, mixed>}>
+	 */
+	public function provider_nested_type_list_output_schemas(): array {
+		$object = fn( array $property ) => array(
+			'type'       => 'object',
+			'properties' => array( 'a' => $property ),
+		);
+		return array(
+			'property type list'             => array( $object( array( 'type' => array( 'string', 'null' ) ) ) ),
+			'oneOf branch type list'         => array( $object( array( 'oneOf' => array( array( 'type' => array( 'string', 'null' ) ), array( 'type' => 'integer' ) ) ) ) ),
+			'deep item type list'            => array(
+				$object(
+					array(
+						'type'  => 'array',
+						'items' => $object( array( 'type' => array( 'integer', 'null' ) ) ),
+					)
+				),
+			),
+			'additionalProperties type list' => array(
+				array(
+					'type'                 => 'object',
+					'additionalProperties' => array( 'type' => array( 'string', 'null' ) ),
+				),
+			),
+			'patternProperties type list'    => array(
+				array(
+					'type'              => 'object',
+					'patternProperties' => array( '^a' => array( 'type' => array( 'string', 'null' ) ) ),
+				),
+			),
+			'allOf branch type list'         => array( $object( array( 'allOf' => array( array( 'type' => array( 'string', 'null' ) ) ) ) ) ),
+		);
+	}
+
+	/**
+	 * @testdox Should register a field whose output schema has a null type or a null branch below the top level.
+	 * @dataProvider provider_nested_null_output_schemas
+	 * @param array $schema Output schema.
+	 */
+	public function test_a_nested_null_in_an_output_schema_is_registered( array $schema ): void {
+		AbilitiesLoader::register_core_resources();
+
+		ExtensibleAbilities::register_field(
+			array(
+				'resource'      => 'order',
+				'namespace'     => 'nested',
+				'field'         => 'value',
+				'output_schema' => $schema,
+				'get_callback'  => '__return_null',
+			)
+		);
+
+		$this->assertArrayHasKey( 'value', ExtensibleAbilities::get_fields( 'order' )['nested'] ?? array() );
+	}
+
+	/**
+	 * Output schemas with a null type or a null branch below the top level.
+	 *
+	 * @return array<string, array{0: array<string, mixed>}>
+	 */
+	public function provider_nested_null_output_schemas(): array {
+		$object = fn( array $property ) => array(
+			'type'       => 'object',
+			'properties' => array( 'a' => $property ),
+		);
+		return array(
+			'property null type'  => array( $object( array( 'type' => 'null' ) ) ),
+			'anyOf null branch'   => array( $object( array( 'anyOf' => array( array( 'type' => 'string' ), array( 'type' => 'null' ) ) ) ) ),
+			'oneOf null branch'   => array( $object( array( 'oneOf' => array( array( 'type' => 'string' ), array( 'type' => 'null' ) ) ) ) ),
+			'allOf null branch'   => array( $object( array( 'allOf' => array( array( 'type' => 'string' ), array( 'type' => 'null' ) ) ) ) ),
+			'nullable list items' => array(
+				array(
+					'type'  => 'array',
+					'items' => array( 'anyOf' => array( array( 'type' => 'number' ), array( 'type' => 'null' ) ) ),
+				),
+			),
+		);
+	}
+
+	/**
+	 * @testdox Should refuse a field whose input schema has a list of types below the top level.
+	 * @dataProvider provider_nested_type_list_input_schemas
+	 * @param array $schema Input schema.
+	 */
+	public function test_a_nested_type_list_in_an_input_schema_is_refused( array $schema ): void {
+		$this->setExpectedIncorrectUsage( ExtensibleAbilities::class . '::register_field' );
+		AbilitiesLoader::register_core_resources();
+
+		ExtensibleAbilities::register_field(
+			array(
+				'resource'     => 'order',
+				'namespace'    => 'refused',
+				'field'        => 'value',
+				'input_schema' => $schema,
+				'set_callback' => '__return_null',
+			)
+		);
+
+		$this->assertArrayNotHasKey( 'refused', ExtensibleAbilities::get_fields( 'order' ) );
+	}
+
+	/**
+	 * Input schemas with a list of types below the top level.
+	 *
+	 * @return array<string, array{0: array<string, mixed>}>
+	 */
+	public function provider_nested_type_list_input_schemas(): array {
+		return array(
+			'property'          => array(
+				array(
+					'type'       => 'object',
+					'properties' => array( 'a' => array( 'type' => array( 'string', 'null' ) ) ),
+				),
+			),
+			'tuple item'        => array(
+				array(
+					'type'  => 'array',
+					'items' => array( array( 'type' => 'string' ), array( 'type' => array( 'integer', 'null' ) ) ),
+				),
+			),
+			'anyOf branch'      => array(
+				array(
+					'type'  => 'object',
+					'anyOf' => array( array( 'type' => array( 'object', 'null' ) ) ),
+				),
+			),
+			'patternProperties' => array(
+				array(
+					'type'              => 'object',
+					'patternProperties' => array( '^a' => array( 'type' => array( 'string', 'null' ) ) ),
+				),
+			),
+			'allOf branch'      => array(
+				array(
+					'type'  => 'object',
+					'allOf' => array( array( 'type' => array( 'object', 'null' ) ) ),
+				),
+			),
+		);
+	}
+
+	/**
+	 * @testdox Should register a field with nested output properties that are not nullable and a nested input anyOf with a null branch.
+	 */
+	public function test_a_nested_schema_without_type_lists_is_registered(): void {
+		AbilitiesLoader::register_core_resources();
+
+		ExtensibleAbilities::register_field(
+			array(
+				'resource'      => 'order',
+				'namespace'     => 'nested',
+				'field'         => 'value',
+				'output_schema' => array(
+					'type'       => 'object',
+					'properties' => array(
+						'tags' => array(
+							'type'  => 'array',
+							'items' => array( 'anyOf' => array( array( 'type' => 'string' ), array( 'type' => 'integer' ) ) ),
+						),
+					),
+				),
+				'get_callback'  => '__return_null',
+				'input_schema'  => array(
+					'type'       => 'object',
+					'properties' => array( 'note' => array( 'anyOf' => array( array( 'type' => 'string' ), array( 'type' => 'null' ) ) ) ),
+				),
+				'set_callback'  => '__return_null',
+			)
+		);
+
+		$this->assertArrayHasKey( 'value', ExtensibleAbilities::get_fields( 'order' )['nested'] ?? array() );
+	}
+
 	/**
 	 * @testdox Should keep the WordPress message for an anyOf under a top-level type whose branches do not each have their own type name.
 	 * @testWith [[{"enum":["small"]},{"enum":["large"]}]]
-	 *           [[{"type":["integer","null"]},{"type":"null"}]]
 	 *           [[{"type":"string","enum":["small"]},{"type":"string","pattern":"^x"}]]
 	 *
 	 * @param array $any_of The anyOf branches.
@@ -1575,12 +1772,12 @@ class ExtensibleAbilitiesTest extends \WC_REST_Unit_Test_Case {
 	 */
 	public function test_valid_schemas_are_published_as_declared(): void {
 		$input_schemas = array(
-			'nullable'    => array( 'anyOf' => array( array( 'type' => 'string' ), array( 'type' => 'null' ) ) ),
-			'any_of'      => array(
+			'nullable'   => array( 'anyOf' => array( array( 'type' => 'string' ), array( 'type' => 'null' ) ) ),
+			'any_of'     => array(
 				'type'       => 'object',
 				'properties' => array( 'a' => array( 'anyOf' => array( array( 'type' => 'string' ), array( 'type' => 'null' ) ) ) ),
 			),
-			'enum_null'   => array(
+			'enum_null'  => array(
 				'anyOf' => array(
 					array(
 						'type' => 'string',
@@ -1589,20 +1786,15 @@ class ExtensibleAbilitiesTest extends \WC_REST_Unit_Test_Case {
 					array( 'type' => 'null' ),
 				),
 			),
-			'enum_mixed'  => array(
+			'enum_mixed' => array(
 				'type' => 'string',
 				'enum' => array( 'a', 1 ),
 			),
-			'branch'      => array(
+			'branch'     => array(
 				'type'  => 'object',
 				'anyOf' => array( array( 'required' => array( 'a' ) ), array( 'required' => array( 'b' ) ) ),
 			),
-			'nested_null' => array(
-				'type'       => 'object',
-				'properties' => array( 'a' => array( 'type' => array( 'string', 'null' ) ) ),
-				'required'   => array( 'a' ),
-			),
-			'different'   => array(
+			'different'  => array(
 				'type'                 => 'object',
 				'properties'           => array( 'delete' => array( 'type' => 'boolean' ) ),
 				'additionalProperties' => false,
@@ -1947,7 +2139,7 @@ class ExtensibleAbilitiesTest extends \WC_REST_Unit_Test_Case {
 					'plain'           => array( 'type' => 'string' ),
 					'nested_declared' => array(
 						'type'       => 'object',
-						'properties' => array( 'a' => array( 'type' => array( 'string', 'null' ) ) ),
+						'properties' => array( 'a' => array( 'anyOf' => array( array( 'type' => 'string' ), array( 'type' => 'null' ) ) ) ),
 					),
 					'nested_refused'  => array(
 						'type'       => 'object',