Determine what goes in Ability meta

[JasonTheAdams]

The wp_register_ability() function has an array $args parameter. This includes data that is required and optional. It also has an $args['meta'] array. The entire $args shape is part of the function signature, so changing it is changing the signature of the function. As such, we should be clear and have a rule for what should be a root element of $args, versus what should belong in $args['meta'].

I propose these rules:

• Required data goes in $args root (e.g. $args['label'])
• Optional data goes in $meta which itself is optional

This is consistent with the parameters as documented.

As such, this would effect things like annotations and show_in_rest, which will become meta. As a note, meta is also the encouraged location for any further arbitrary data extended by developers — which will also be optional at least as far as registration is concerned.

[JasonTheAdams]

We should make a decision on this quickly so we can document this and make any necessary changes. For PRs such as #103, I think we should just merge that PR and then make a subsequent PR for moving anything that's currently in the root which we want to move to meta.

[gziolo]

As such, this would effect things like annotations and show_in_rest, which will become meta.

Would you suggest merging meta with annotations or rather moving annotations as a group under meta?

Overall, I’m happy to make a final decision so we have clear path for future additions.

[justlevine]

I propose these rules:

• Required data goes in $args root (e.g. $args['label'])
• Optional data goes in $meta which itself is optional

Not sure this is the best delineation since it just kicks the question to "what data should be required".

• Per this definition, it's not just annotations or show_in_rest that get relocated, but also the input_schema, output_schema, and ability_class that should be moved. To me that placement feels counterintuitive. (The documentation in https://github.com/WordPress/abilities-api/blob/trunk/docs/3.registering-abilities.md#parameters-explained seems out of date).
• ability_class technically makes all properties optional, so the polymorphic footgun now also affects DX semantics.

I propose the following rules instead:

• $args: Data required to identify and execute the ability goes in root
• Everything else is "additional metadata about the ability" and belongs in the optional $args['meta'].

This is imo more consistent with the current docs/implementation and also more intuitive:

Element	Location	Reason
label, description, (arguably) category	$args	used for basic identification
execute_callback, permission_callback	$args	required core logic for (secure) execution
input_schema, output_schema	$args	(if supplied) validates and determines the shape of the ability.
ability_class	$args	(if supplied) use this to execute the ability instead of the core WP_Ability class`
---	---	---
show_in_rest, *_mcp, *_acp	$args['meta']	Used by last-mile adapters to filter visibility
annotations	$args['meta']	Whether as an MCP-specific requirement or theoretically in more abstract scenarios, it's still contextual metadata used by the executor of the ability not the ability itself.

This seems to scale pretty well with other hypothetical properties too, but please share any edge cases you think are ambiguous.

It also has the benefit of keeping our API small in these initial stages while we're still theorycrafting. As noted in #103 (comment), leveraging $meta means we avoid stuffing our WP_Ability with more protected properties and public methods that we can't remove from core, exacerbate the aforementioned ability_class footgun. We can always "graduate" an $args['meta'] to a root-level argument

[JasonTheAdams]

Not sure this is the best delineation since it just kicks the question to "what data should be required".

True. But I think that's a reasonable first question to ask, and the answer will usually be no.

I propose the following rules instead:

• $args: Data required to identify and execute the ability goes in root
• Everything else is "additional metadata about the ability" and belongs in the optional $args['meta'].

I think that's a reasonable definition, though we're still saying "data required" and I think you're put with things like input_schema is that they're not required.

More to the point, I agree with your table of where things go. That makes sense to me. 👍

[gziolo]

I’m starting updating the usage of annotations and show in REST based on the discussion above.

[gziolo]

I have all the changes ready for review regarding show_in_meta:

• Move show_in_rest to meta in the registration process #107

I will now repurpose #104 to include both the documentation and the changes to move annotations to meta.