Editor: Create standalone JSON schema for block type definition

[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.

[coreymckrill]

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?

[coreymckrill]

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

[schlessera]

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.

[coreymckrill]

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...

[coreymckrill]

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

[TimothyBlynJacobs]

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.

[coreymckrill]

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.

[gziolo]

It looks like we settled on the i18n schema for both block.json and theme.json. The most recent work for block.json:
​https://github.com/WordPress/gutenberg/pull/30293

It looks this way:

{
	"title": "block title",
	"description": "block description",
	"keywords": [ "block keyword" ],
	"styles": [
		{
			"label": "block style label"
		}
	],
	"variations": [
		{
			"title": "block variation title",
			"description": "block variation description",
			"keywords": [ "block variation keyword" ]
		}
	]
}

It should be enough to use it as a shared schema for WP-CLI and WP core. The question is how would it be consumed? In WP Core we could copy the file with webpack from the published npm module. What would be the preference for WP CLI?

[gziolo]

We also have a JSON schema for block.json files at:

​https://github.com/WordPress/gutenberg/blob/trunk/schemas/json/block.json