Abilities API: Encode empty object results as JSON objects by jorgefilipecosta · Pull Request #14547 · WordPress/wordpress-develop

jorgefilipecosta · 2026-10-20T12:39:56Z

Follow up to https://core.trac.wordpress.org/changeset/64592 (#14139) and https://core.trac.wordpress.org/changeset/64689 (#14671).

What

The run endpoint prepares every result for JSON clients with wp_prepare_json_value_for_client(), not only associative arrays. An empty array returned for an object output schema is now encoded as {} at the root, in lists, and inside object or JsonSerializable results, instead of [], which the JS client (executeAbility()) rejected with ability_invalid_output. This fixes it for all abilities, e.g. core/settings-get when no setting matches.
Arrays stay arrays: an empty list or a list of strings is still encoded as [].
The run handler sets the data_processing route option (from https://core.trac.wordpress.org/changeset/64689) to false, so _fields, _embed and response links leave the result unchanged, and it follows the ability's output schema whether it is an object, an array, or a scalar value. The REST API client fixture lists the disabled processing for the run endpoint.

await wp.apiFetch( { path: wp.url.addQueryArgs( '/wp-abilities/v1/abilities/core/settings-get/run', { input: { group: 'writing', fields: [ 'title' ] } } ) } );
// Before: []
// After:  {}

await wp.apiFetch( { path: wp.url.addQueryArgs( '/wp-abilities/v1/abilities/core/settings-get/run', { input: { group: 'writing', fields: [ 'title' ] }, _fields: 'title' } ) } );
// After:  {}

Issue found while testing the query abilities through the JS client; the fix was drafted with AI assistance and reviewed by me.

Trac ticket: https://core.trac.wordpress.org/ticket/66267

Testing

Verify unit tests are passing:

npm run test:php -- --filter 'test_output_is_prepared_for_json_clients|test_no_matching_setting_is_encoded_as_an_empty_object'

github-actions · 2026-10-20T12:40:06Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs.

Core Committers: Use this line as a base for the props when committing in SVN:

Props jorgefilipecosta, gziolo.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

Props Bot commands

You can trigger Props Bot actions by commenting on this PR:

@propsbot add <username> to give props to a GitHub user. Requires write access.
@propsbot remove <username> to leave a user out of the props. Requires write access.
@propsbot refresh to refresh this list. Adding the props-bot label works too.

github-actions · 2026-10-20T12:43:38Z

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

All changes will be lost when closing a tab with a Playground instance.
All changes will be lost when refreshing the page.
A fresh instance is created each time the link below is clicked.
Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

gziolo · 2026-10-20T13:15:40Z

I noted in #14139 that we should follow-up and figure out how to map [] to {} in a way that doesn't break REST API handler when global handlers like _fields or _links get passed. Casting to (object) in the ability doesn't resolve the problem.

jorgefilipecosta · 2026-10-21T11:10:58Z

I noted in #14139 that we should follow-up and figure out how to map [] to {} in a way that doesn't break REST API handler when global handlers like _fields or _links get passed. Casting to (object) in the ability doesn't resolve the problem.

Hi @gziolo this PR was updated and addressed these issues.

gziolo · 2026-10-21T13:22:48Z

Could we let controllers explicitly opt out of _fields filtering, _embed processing, and response link injection?

The problem extends beyond objects to scalar values, where these transformations have no meaningful application. Currently, _fields can trigger a type error, embedding silently does nothing, and link injection can fail or change the response’s type. Broadening array-specific helpers to accept arbitrary values doesn’t establish consistent support for these features.

The ability execution controller could disable all three explicitly, preserving the ability’s output schema and making behavior predictable regardless of whether the result is an object, array, or scalar.

jorgefilipecosta · 2026-10-21T19:38:26Z

Could we let controllers explicitly opt out of _fields filtering, _embed processing, and response link injection?

Hi @gziolo, Currently there is no way to opt out, following your feedback I'm proposing it at #14671.

gziolo

A few suggestions to make the test cases easier to follow and strengthen coverage of the response-preservation behavior.

gziolo · 2026-10-22T12:41:24Z

+
+		$data = array();
+		foreach ( $results as $label => $result ) {
+			foreach ( array( 'none', '_fields', '_embed', 'link', 'embedded link' ) as $global_param ) {


$global_param contains both query parameter names and instructions for setting up the test, such as link and embedded link. This makes the cases harder to follow.

Could we consider passing query parameters directly from the provider, for example array( '_fields' => 'other', '_embed' => '1' ), and applying them with $request->set_query_params()? Link setup could be a separate argument. This would also make it easy to test both parameters together.

gziolo · 2026-10-22T12:41:24Z

+			add_filter(
+				'rest_post_dispatch',
+				static function ( $response ) {
+					$response->add_link( 'alternate', rest_url( '/wp-abilities/v1/abilities' ), array( 'embeddable' => true ) );


This test adds a link to the response metadata. Since link injection is disabled, that link never reaches the response body. The test therefore does not check what happens when the ability’s output already contains _links.

Could we consider adding a case where the ability returns its own _links property with an embeddable link? With _embed=1, we could check that the output stays unchanged and no request is made to fetch the linked resource.

gziolo · 2026-10-22T12:41:24Z

+
+		add_filter( 'rest_post_dispatch', 'rest_filter_response_fields', 10, 3 );
+		$response = apply_filters( 'rest_post_dispatch', $response, $this->server, $request );
+		$data     = $this->server->response_to_data( $response, isset( $global_params['_embed'] ) );


This test manually calls the steps that process and encode the response. It checks those steps, but it does not check the body sent by serve_request().

Could we consider using serve_request() for this regression test, passing the input and query parameters through the normal request path and checking the emitted JSON? We could verify that the body is {} when _fields and _embed are supplied together. The broader output-shape tests could keep their current approach.

gziolo · 2026-10-22T12:43:51Z

-			'numeric collection stays unchanged' => array( 'test/empty-object-list-output', '[[]]' ),
-		);
+		$results = array(
+			'root empty object'       => array( 'test/empty-object-output', '{}' ),


This case checks that a root empty object is encoded as {} when the response is served. Preloaded requests take a different path. rest_preload_api_request() casts the data with (array), and that turns the stdClass back into an empty array. So the preloaded body becomes [], and a scalar like "value" becomes ["value"].

Could we consider adding a preload test for a read-only ability (preloading only allows GET) that returns an empty object and a scalar? Today it would fail for both. The fix could be to skip the (array) cast in rest_preload_api_request(), either here or in #14671 since that PR covers preloaded requests.

gziolo · 2026-10-23T07:29:29Z

I approved #14671, so let's commit it, and I will finish reviewing this one. Currently, it contains changes from both.

gziolo · 2026-10-29T10:32:21Z

@jorgefilipecosta, do we still want to include this in WordPress 7.2?

The run endpoint prepared only associative array results for JSON clients, so an empty array returned for an object output schema, such as the `core/settings-get` result when no setting matches, was encoded as [] and failed output validation in JSON clients. Prepare every result, including root results, lists and object results, so empty objects are encoded as {} while arrays stay arrays. Register the run endpoint with the `data_processing` route option set to `false`, so the `_fields` and `_embed` parameters and response links leave the result unchanged and it follows the ability's output schema whether it is an object, an array, or a scalar value. The REST API client fixture lists the disabled processing for the run endpoint. Follow-up to [64311], [64592], [64689]. See #66267.

jorgefilipecosta changed the title ~~Abilities API: Preserve empty object results in REST responses~~ Abilities API: Return an empty object from core/settings-get when no setting matches Oct 20, 2026

jorgefilipecosta force-pushed the fix/abilities-empty-object-result branch from 8e657ba to 29c2ab8 Compare October 20, 2026 13:05

jorgefilipecosta force-pushed the fix/abilities-empty-object-result branch from 29c2ab8 to 0437a0b Compare October 20, 2026 13:26

jorgefilipecosta changed the title ~~Abilities API: Return an empty object from core/settings-get when no setting matches~~ Abilities API: Encode empty object results as JSON objects Oct 20, 2026

jorgefilipecosta force-pushed the fix/abilities-empty-object-result branch from 0437a0b to e68fd10 Compare October 20, 2026 13:33

jorgefilipecosta changed the title ~~Abilities API: Encode empty object results as JSON objects~~ Abilities API: Return an empty object from core/settings-get when no setting matches Oct 20, 2026

jorgefilipecosta force-pushed the fix/abilities-empty-object-result branch from e68fd10 to d05b08b Compare October 20, 2026 13:51

jorgefilipecosta changed the title ~~Abilities API: Return an empty object from core/settings-get when no setting matches~~ Abilities API: Encode empty object results as JSON objects Oct 20, 2026

jorgefilipecosta force-pushed the fix/abilities-empty-object-result branch from d05b08b to 9d63d51 Compare October 20, 2026 14:12

jorgefilipecosta mentioned this pull request Oct 21, 2026

REST API: Let routes turn off _fields, _embed and response links #14671

Closed

jorgefilipecosta force-pushed the fix/abilities-empty-object-result branch from 9d63d51 to 374b904 Compare October 21, 2026 19:32

gziolo reviewed Oct 22, 2026

View reviewed changes

jorgefilipecosta force-pushed the fix/abilities-empty-object-result branch from 374b904 to cd02d31 Compare October 22, 2026 14:40

jorgefilipecosta force-pushed the fix/abilities-empty-object-result branch from cd02d31 to 0ac67da Compare October 29, 2026 13:38

Conversation

jorgefilipecosta commented Oct 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Testing

Uh oh!

github-actions Bot commented Oct 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Oct 20, 2026

Test using WordPress Playground

Some things to be aware of

Uh oh!

gziolo commented Oct 20, 2026

Uh oh!

jorgefilipecosta commented Oct 21, 2026

Uh oh!

gziolo commented Oct 21, 2026

Uh oh!

jorgefilipecosta commented Oct 21, 2026

Uh oh!

gziolo left a comment

Choose a reason for hiding this comment

Uh oh!

gziolo Oct 22, 2026

Choose a reason for hiding this comment

Uh oh!

gziolo Oct 22, 2026

Choose a reason for hiding this comment

Uh oh!

gziolo Oct 22, 2026

Choose a reason for hiding this comment

Uh oh!

gziolo Oct 22, 2026

Choose a reason for hiding this comment

Uh oh!

gziolo commented Oct 23, 2026

Uh oh!

gziolo commented Oct 29, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jorgefilipecosta commented Oct 20, 2026 •

edited

Loading

github-actions Bot commented Oct 20, 2026 •

edited

Loading