Feature Proposal: Categories for Abilities API

[galatanovidiu]

Summary

Add a required category system to the WordPress Abilities API to enable organizing, filtering, and discovering abilities by functional domain. Every ability must be assigned to a category.

---

Problem

The Abilities API currently lacks a native way to:

• Organize abilities by functional area (content, users, e-commerce, etc.)
• Filter abilities in REST API queries
• Group related abilities for UI rendering and documentation
• Enable taxonomy-style organization

---

Proposed Solution

Implement a category system with these characteristics:

• Required property - Every ability must have a category assigned
• Required registration - Categories must be registered before they can be assigned to abilities
• First-class property - Category stored as ability property, not in metadata
• Registry pattern - Category registry manages all available categories with labels and descriptions
• REST API integration - Native filtering via query parameters
• WordPress patterns - Follows post types/taxonomies conventions

---

Core Components

1. Category Class

New: WP_Ability_Category

Properties:

• slug - Unique identifier (pattern: ^[a-z0-9-]+$)
• label - Human-readable name
• description - Detailed description

2. Category Registry

New: WP_Abilities_Category_Registry

Pattern: Singleton registry (required for all categories)

Functionality:

• Register/unregister categories
• Retrieve categories by slug
• List all registered categories
• Check if category is registered (used during ability registration)
• Validate category before ability assignment

Hook: abilities_api_category_registry_init

3. Ability Integration

Enhancement: WP_Ability class

New Property: category (string, required)

Validation:

• Must be a non-empty string
• Enforce slug pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
• Lowercase alphanumeric characters and dashes only

4. Helper Functions

New functions in abilities-api.php:

Registration:

• wp_register_ability_category()
• wp_unregister_ability_category()

Retrieval:

• wp_get_ability_category()
• wp_get_ability_categories()

Filtering:

• wp_get_abilities_by_category()

5. REST API

Schema Enhancement:

• Add category field to ability response
• Type: string with pattern validation
• Context: view, edit, embed
• Readonly: true
• Required: true

Query Parameter:

• GET /wp/v2/abilities?category=content
• Filter abilities before pagination
• Return standard paginated response

6. Registry Enhancement

New method in WP_Abilities_Registry:

• get_abilities_by_category() - Filter abilities by category slug

---

Proposed Design Approach

1. Required Category Property with Required Registration

Proposal: Every ability must have a category, and categories must be formally registered before they can be assigned to abilities.

Benefits:

• Ensures consistent organization across all abilities
• Prevents typos and inconsistent category names
• Provides centralized category management with labels and descriptions
• Enables better documentation and discovery of available categories
• Validates category slugs at registration time

2. Simple Category Structure

Proposal: Keep categories simple with only slug, label, and description.

Benefits:

• YAGNI principle (keep it simple)
• Clearer purpose (organization and labeling)
• Easier to understand and maintain
• Can be extended later if needed

3. First-Class Required Property

Proposal: Store category as a required direct WP_Ability property.

Benefits:

• Easier to access via $ability->get_category()
• Enforces validation rules at the class level
• Automatically included in REST API responses
• Guarantees every ability is categorized

4. Slug Pattern Enforcement

Proposal: Enforce ^[a-z0-9]+(-[a-z0-9]+)*$ pattern for category slugs.

Benefits:

• Prevents special characters, spaces, uppercase
• Ensures proper dash usage (no leading, trailing, or consecutive dashes)
• URL-safe for REST API
• Consistent with WordPress conventions
• Prevents data integrity issues

Backward Compatibility

Breaking Changes: Yes - Category is now required and must be registered

Impact:

• Categories must be registered using wp_register_ability_category() before use
• All existing abilities must be updated to include a registered category
• Ability registration without category will fail validation
• Ability registration with unregistered category will fail validation
• Existing REST API queries unaffected (category filtering is optional)
• Migration needed:
  1. Register all required categories
  2. Update all abilities to use registered categories

[gziolo]

Excellent proposal that addresses the requirements shared by @JasonTheAdams in #83 (comment). Two things that I'm not entirely sure whether should be included in the final solution for category feature:

• abilities_api_category_registry_init seems to duplicate abilities_api_init. In particular, I would like to better understand what value an independent action for category registration would bring at the cost of forcing developers to code two action callbacks when registering a single ability with a custom category.
• We definitely need something like wp_get_abilities_by_category(), but I would be more in favor of making wp_get_abilities() general-purpose instead by allowing filtering like wp_get_abilities( [ 'category' => 'content' ] );. That we can tackle separately with Proposal: Add a convienient way to filter the list of all registered abilities #38.

[galatanovidiu]

• abilities_api_category_registry_init seems to duplicate abilities_api_init. In particular, I would like to better understand what value an independent action for category registration would bring at the cost of forcing developers to code two action callbacks when registering a single ability with a custom category.

The separate abilities_api_category_registry_init hook may seem redundant at first, but it serves an important architectural purpose: ensuring guaranteed execution order.

Categories must exist before abilities that reference them can be registered. Without a separate hook, we'd rely on action priorities to enforce this order, which becomes problematic in cross-plugin scenarios.

Example:

WooCommerce defines a woocommerce category. Suppose another plugin wants to register abilities using the same category. In that case, there's no reliable way to ensure WooCommerce's category registration runs first when both use the same abilities_api_init hook, unless they coordinate specific priority values, which is fragile.

With the separate hook:

• WooCommerce registers categories on abilities_api_category_registry_init
• Other plugins confidently use those categories on abilities_api_init
• The execution order is architecturally guaranteed

We could remove the separate hook, but that would shift the complexity to runtime validation and priority coordination, making issues harder to debug and more dependent on conventions.

• We definitely need something like wp_get_abilities_by_category(), but I would be more in favor of making wp_get_abilities() general-purpose instead by allowing filtering like wp_get_abilities( [ 'category' => 'content' ] );. That we can tackle separately with Proposal: Add a convienient way to filter the list of all registered abilities #38.

Yes, we can remove this functionality. It will be nice to have this general filter sooner than later :)

[gziolo]

Categories must exist before abilities that reference them can be registered. Without a separate hook, we'd rely on action priorities to enforce this order, which becomes problematic in cross-plugin scenarios.

Do we really need to enforce the requirement that a category must be registered before it can be referenced. You may still encounter a situation where a category gets registered, but then, for some reason, someone unregisters it. What do you do in that case? Do you deregister also all abilities that use the same removed category? These different scenarios are challenging to cover perfectly in a system as extensible as WordPress. In particular, I'm concerned that we are trying to create too strict requirements, where low-impact properties, such as the label for the category, dictate the API design choices. Even when providing a simple slug, you still can support filtering by category. In this case, when these labels/descriptions exist, they can be passed to LLMs as additional hints, but otherwise, passing a slug could also be helpful.

@JasonTheAdams, I would be happy to hear your perspective as you have better context for this particular feature based on your practical experience.

[galatanovidiu]

I'm happy to make this loosely coupled.

However, I want to ensure we're aligned on the implications:

• Runtime flexibility: Plugins can reference categories without strict registration requirements
• Validation trade-off: We lose the architectural guarantee that categories exist before abilities reference them

[gziolo]

Let's wait for more feedback, including clarification from @JasonTheAdams. That's a good summary of the implications 👍🏻