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',