WordPress.org

Make WordPress Core

Opened 4 months ago

Last modified 3 months ago

#50615 new feature request

Editor: Create standalone JSON schema for block type definition

Reported by: gziolo Owned by:
Milestone: Awaiting Review Priority: normal
Severity: normal Version:
Component: Editor Keywords:
Focuses: rest-api Cc:

Description (last modified by gziolo)

There is an existing schema for block type definition embedded in the new REST API endpoint:

https://github.com/WordPress/wordpress-develop/blob/c3993eb19dee52dfd6ca9f9ef7cec785538e361d/src/wp-includes/rest-api/endpoints/class-wp-rest-block-types-controller.php#L363-L569

There is also another schema being developed for Block Directory that will take part in block.json file validation:

https://github.com/tellyworth/plugin-directory/blob/25388b9c12193194a16db5264ed84f2f3965552e/block-json/class-validator.php#L36-L182

It would be great to consolidate efforts and make such schema publicly accessible as it would benefit other projects in the WordPress ecosystem like WP-CLI. There is a related discussion related to translatable strings extraction, see https://github.com/wp-cli/i18n-command/pull/210#issuecomment-634107470

This kind of schema would need to live somewhere outside of WordPress context, where WP-CLI and other tools can easily assess which fields in block.json are translatable and which aren't.

All that would make it also possible to easily extend the schema in one place and related tools consuming it could automatically adjust their behavior based on the changes applied.

Change History (8)

#1 @gziolo
4 months ago

  • Description modified (diff)

#2 @coreymckrill
3 months ago

As @swissspidy mentioned, a good place for this schema would probably be somewhere on wordpress.org. What about an API endpoint, something like this?

https://api.wordpress.org/schema/block/1.0/

that returns a JSON respond of the schema?

#3 @coreymckrill
3 months ago

@schlessera given this comment I'm wondering if you have any thoughts about where the canonical source of the block.json schema should live...

#4 @schlessera
3 months ago

I think it should probably be something shipped with Core, to properly version the schema in accordance with the Core version in use. Otherwise, you'd need to have an argument to version the API endpoint requests with, and you'd need to always update the API endpoint during the development cycle of Core if changes are needed.

The important bit is that it shouldn't be logic you need to execute within the runtime context of WordPress, but rather static information you can just read even if WordPress is not running, like a static JSON file.

It could be something like wp-includes/blocks/schema.json, for example. I know that wp-includes would generally be considered PHP includes, but there are already JSON files in the wp-includes/blocks subfolders that set a precedent.

#5 @coreymckrill
3 months ago

I think it should probably be something shipped with Core, to properly version the schema in accordance with the Core version in use. Otherwise, you'd need to have an argument to version the API endpoint requests with, and you'd need to always update the API endpoint during the development cycle of Core if changes are needed.

That makes sense. I could also imagine that there are/will be other schemas that it would be useful to have accessible outside of a runtime context. So perhaps a structure like this?

wp-includes/schemas/block-type.json

Then for the block types REST API endpoint there would be a method that loads that json file and decodes it into an associative array (which could also be used by the block.json validator in the plugin directory).

My understanding is that one reason for doing this would be so that certain fields could be marked as translatable in the schema. Ironically, the schema itself (as it currently exists within the REST API endpoint) has translatable fields, mostly descriptions. I'm not sure how we would handle those...

#6 @coreymckrill
3 months ago

@TimothyBlynJacobs just read your summaries of REST API changes for 5.5 on Make/Core. Any thoughts on this issue?

#7 @TimothyBlynJacobs
3 months ago

I agree with @schlessera, I think a static .json file would be very helpful.

That makes sense. I could also imagine that there are/will be other schemas that it would be useful to have accessible outside of a runtime context. So perhaps a structure like this?

That'd definitely be more forward compatible, though I don't think there are many instances where it'd make sense. Many REST API schema definitions are dynamic based on what features are enabled for the resource.

Ironically, the schema itself (as it currently exists within the REST API endpoint) has translatable fields, mostly descriptions. I'm not sure how we would handle those...

Yeah the translatable fields would pose an issue. I guess we could run the description fields thru translate, but that'd require the strings somehow being added to GlotPress.

Another potential issue with loading from a .json file would be if Gutenberg is active the plugin could need a way to add more fields to the schema.

#8 @coreymckrill
3 months ago

Many REST API schema definitions are dynamic based on what features are enabled for the resource.

Good point. Though if the schema in the json file was comprehensive, it could be whittled down in the get_item_schema method after decoding the json to a PHP array, based on the current state.

Another potential issue with loading from a .json file would be if Gutenberg is active the plugin could need a way to add more fields to the schema.

Yeah, there would need to be an apply_filters call sometime after decoding the json to PHP.

Note: See TracTickets for help on using tickets.