REST API, Meta: Allow leaving out meta keys without a stored value - #14831

Registered meta that's shown in the REST API is always included in responses, using its default when nothing is stored. A client that saves a response back then stores that default for keys nobody changed. The block editor does this whenever any meta key is edited, since it sends back the whole meta object (WordPress/gutenberg#17864).

This adds the option @TimothyBJacobs suggested on the ticket: an omit_if_not_exists key for the show_in_rest argument of register_meta().

register_post_meta( 'post', 'my_meta', array(
	'show_in_rest' => array( 'omit_if_not_exists' => true ),
	'single'       => true,
	'type'         => 'string',
) );

When it's true, WP_REST_Meta_Fields::get_value() leaves the key out of the response until a value is stored. It reads meta with get_metadata_raw(), which returns null when nothing is stored, and only falls back to the registered default for keys without the option. Once a value is stored, even an empty string, the key shows up as usual.

• It's opt-in, so responses for existing keys don't change.
• The schema still lists the key, so clients can keep setting it.
• It's in WP_REST_Meta_Fields, so it works for post, term, comment and user meta.

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

Testing

New tests in tests/phpunit/tests/rest-api/rest-post-meta-fields.php (--group 48478, 9 cases). Without the change, the 5 that cover leaving keys out fail. The other 4 check that stored values (an empty string and multiple values too) and the schema work as before. The 3 cases for leaving keys out also check that a key without the option is still included.

The restapi run has the same 4 warnings as trunk (test_get_items_wdotorg_unavailable, test_create_item_wdotorg_unreachable and the two test_format_validation_is_applied_if_missing_type tests).

PHPCS and PHPStan are clean on the changed lines.

I also checked it in the block editor on a local wordpress-develop site, with two regular keys and one using omit_if_not_exists. After editing one of the regular keys and saving a draft:

Manual testing

1. Add this as an mu-plugin:

   <?php
   add_action( 'init', function () {
   	foreach ( array( 'demo_edited', 'demo_regular' ) as $key ) {
   		register_post_meta( 'post', $key, array( 'show_in_rest' => true, 'single' => true, 'type' => 'string' ) );
   	}
   	register_post_meta( 'post', 'demo_omitted', array(
   		'show_in_rest' => array( 'omit_if_not_exists' => true ),
   		'single'       => true,
   		'type'         => 'string',
   	) );
   } );

2. Go to "Posts > Add New Post".
3. In the browser console, run wp.data.dispatch( 'core/editor' ).editPost( { meta: { demo_edited: 'Changed' } } );
4. Click "Save draft", then run npm run env:cli -- post meta list <ID>.
   • Before: demo_omitted is stored with an empty value.
   • After: demo_omitted isn't stored. demo_edited and demo_regular are stored as before.

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 5.5
Used for: Writing the change and the PHPUnit tests, the block editor check, and drafting this description. I reviewed the code and the test results before opening this PR.

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.