Proposal: add subcategories to block.json

[vcanales]

As discussed in the ongoing GitHub issue #53431, the current implementation of block categories in WordPress allows for a flat structure where blocks are grouped into high-level categories such as "text," "media," "design," etc. However, as the ecosystem of blocks grows, this flat structure becomes increasingly difficult to manage and navigate, especially when dealing with more complex themes and plugins.

Subcategories offer a solution by allowing blocks to be further organized within parent categories, adding valuable granularity. In this proposal, I’m suggesting an addition to the block.json schema that enables the use of subcategories and constrains their assignment to specific parent categories. This approach ensures a well-documented and structured categorization system, preventing misuse and maintaining consistency across blocks.

Proposed Schema

1. Explicit Subcategory Definitions: Define which subcategories belong to which parent categories. This ensures that only relevant subcategories are available within a given parent category, enhancing the organization and discoverability of blocks.
2. Schema Validation Enhancements: Modify the JSON schema to allow references between categories and their allowed subcategories. For instance, a subcategory could reference its parent category, ensuring that only blocks that belong to a valid parent-child relationship can be categorized accordingly.
3. Granularity in Block Organization: By enforcing these relationships, extenders will be able to categorize blocks more precisely, making the block inserter more helpful and user-friendly. This would be particularly beneficial in large projects with numerous blocks, where the ability to filter and search based on subcategories could enhance their discoverability.

Parent-Child Relationships in the Proposed Schema

1. Category as the Parent
   The category property represents the primary grouping of blocks. Categories are broad and cover major areas like "text," "media," "design," "widgets," "theme," and "embed." Each block must be assigned to one of these categories.

• Current Categories:
  • Text
  • Media
  • Design
  • Widgets
  • Theme
  • Embed

2. Subcategory as the Child
   Suggested initial Subcategories (based on Style Book: Iterate on presentation and design #53431)

• Under theme
  • Site Identity
  • Design
  • Posts
  • Comments

Schema Constraints and Relationships

The schema introduces constraints that bind specific subcategories to their appropriate parent categories. This ensures that a subcategory can only be used under its designated parent category.

Implementation Example

The subcategory property includes a parent field that references the valid parent category from the category enum. For example:

"dependencies": {
    "category": {
      "oneOf": [
        {
          "properties": {
            "category": { "enum": [ "theme" ] },
            "subcategory": {
              "enum": [
                "site identity",
                "design",
                "posts",
                "comments"
              ]
            }
          }
        }
      ]
    }
  }

In this example, "Site Identity," "Design," "Posts," and "Comments" are subcategories that can only exist under the "theme" category.

Enforced Relationships

The schema ensures that subcategories are only available within their designated parent category. For example, the "Design" subcategory is valid under "theme" but cannot be mistakenly used under another category like "text" or "media." This strict enforcement maintains logical and consistent block organization.

Benefits

• Improved User Experience: Users can more easily find and insert blocks into their content, as blocks will be categorized in a way that makes logical sense.
• Developer Control: Developers gain more control over how their blocks are presented to users, allowing for a more curated and intentional block browsing experience.
• Consistency Across Themes and Plugins: Standardizing how categories and subcategories are defined and used will allow for consistency across themes and plugins that take advantage of this categorization option.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: vcanales <vcanales@git.wordpress.org>

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

[richtabor]

...wasn't sure if it warranted updating the block.json schema (and every block.json file) just yet when things could be hard-coded for the first iteration.

I agree with this sentiment from @ramonjd here: #53431 (comment)

I think we close this for now, to potentially revisit.