Analyze using block.json to register Gutenberg blocks in the GraphQL schema

[leoloso]

block.json will be available starting from WordPress 5.8 to register block types. The GraphQL API could read this information and, dynamically, create types for these blocks, to be registered in the schema.

Analyze if this path is doable, advantages and potential problems from implementing this approach.

References:

• Block API Enhancements in WordPress 5.8
• Block Metadata | Block Editor Handbook

Compare approach against:

• 💬 Proposing a new approach for 'Gutenberg and Decoupled Applications'

[leoloso]

A tradeoff is that the plugin will require minimum version of WordPress 5.8.

But that's no big deal, since the update to the latest version of WordPress seems to happen very quickly. According to the WordPress stats, 47.4% of WP sites are currently running the latest version, 4.7.

In addition, to support Application Passwords the plugin would require WP >= 5.6.

Also, the code using one filter hook or another to support WP 5.8 can be removed: #711

What other features would then become readily available? Maybe new features related to FSE can be added made available via the GraphQL API?

[leoloso]

No need to have the whole plugin require WP 5.8! Gutenberg blocks can be enabled with a module, and only that module can be made to require WP 5.8.

[leoloso]

Better not tackle this issue yet, because the new "Full Site Editing" feature will change how blocks are accessed.

For instance, WP 5.8 has deprecated hook block_categories (see #711) to add support to pass WP_Block_Editor_Context instead of a WP_Post.

Then, with FSE, blocks may be everywhere, not only under Post type.

So it's better to wait, for at least WP 5.9 or above, as to implement a more comprehensive logic.

[marceloomens]

Hi, I'd be really keen to hear what the status is on this, now that the first beta of WP5.9 has been released. I'd love to see support for blocks and the blockMetadata field for GraphQL. Is there something I can do to help or is this still on hold awaiting further developments in Wordpress?

[leoloso]

@marceloomens Check this tweet and follow the thread all the way up: https://twitter.com/gziolo/status/1464086659734065152

We already have block.json that provides the type of each block. However, when the type is array or object, it keeps it there, without defining which is the actual type (String, Int or what). So that's an issue for GraphQL.

Would you like to help introduce the strong typing into block.json? (Greg Ziółkowski, who is the main maintainer of block.json, seems to approve of this idea). Once that happens, the GraphQL API for WP (as much as WPGraphQL) can fully retrieve the block metadata and map it to the GraphQL schema. Before then, support for arrays and objects would be handicapped.

[marceloomens]

I'm trying to wrap my head around this a little @leoloso. I suppose my lack of real understanding of GraphQL, especially beyond what's is required of an API consumer, is a problem here. I understand from your comment that GraphQL is / required schemas to be strongly typed and does not allow for nodes / leaf nodes to be of some type any?

I'm a quick learner though. If you have a good primer for me on the GraphQL spec, I'd be very happy to look into it.

[leoloso]

Ideally speaking, you need to strictly type the GraphQL schema (as much as possible). It's one of the founding concepts of GraphQL: by having strong types, you can define a clear contract between the server, the client and the different tools. (Eg: it allows GraphiQL to interact with the GraphQL server).

Sometimes it's not possible to know if an entity is a String or an Int, and because of that I introduced the AnyScalar type in the previous release, so we can always use this type instead of Scalar or Int. But that's a bit of a hack, that we'd rather avoid if possible. For instance, GraphQL clients will not know that AnyScalar can receive a String, and so it may show a warning.

A bigger issue is when an array contains another array: [[String]]. Then representing the field as [AnyScalar] can generate issues. For instance, if you pass this value to a function which doesn't expect an array, it will throw a runtime exception. To avoid the problem, you'd have to check if the type is an array or not, creating bloated code here and there. So we'd rather avoid this.

Hence, ideally we should strive to strong type the schema. The thing is that it is doable, because that effort has already been implemented in the WP REST API, so it makes a lot of sense. (As I mention in the Twitter thread)

Btw, if you want to learn about the GraphQL spec, do read it: https://spec.graphql.org/draft/ (it's not difficult at all). Another good source of knowledge is https://graphql.org/learn/. If you have any specific doubt, please do ask me.

[marceloomens]

I've been reading up a little on GraphQL, only to learn that JSON Schema is probably a more appropriate technology to read up on for this particular issue :-)

Am I right to assume that this mostly / exclusively related to the type attribute on patternProperties, because that's the only place where I find "untyped" array and object leaf nodes?

I have to say I'm finding this quite esoteric stuff, coming into (headless) Wordpress development from outside and with very little prior knowledge of and experience with the relevant technologies.

[leoloso]

This development would be for Gutenberg, under its repo, so you'd need to use its technologies. I guess in this case that would be JavaScript/TypeScript and, possibly, the JSON schema.

The new data should be placed on block.json, but exactly how or where, I don't know. If you decide to work on this issue, maybe you can first create an issue on the Gutenberg repo proposing to fully type the schema, why and how it would benefit GraphQL (not only this plugin, but also WPGraphQL). Then you could reach out to the maintainers working on this similar issue, ask if they agree with it and, if so, ask them for guidance.