Automatic Tooltips & Validation for theme.json & block.json Files!

Just a quick post today about improving the editing experience for theme.json and block.json files.

Recently, I’ve been busy learning as much as I can about full site editing (FSE) and block themes. I had planned to do the next few articles on these topics but unfortunately, I need more time to assimilate all the material I’ve covered. There’s much more to it than anticipated and I don’t want to rush producing content and risk inaccuracies or miss out anything important.

Another issue with writing about FSE and block theme development at the moment is that it’s evolving at such a rapid pace. Articles can quickly become out of date which makes writing a constant challenge.

So, for now, I’m just taking a step back to consider the best approach to tackle these new exciting topics. Anyway, all that’s for upcoming articles. Onto today’s post.

What Is theme.json Anyway?

If you’ve been following along with block theme development then you’ll be familiar with the theme.json file format. This is brand new to WordPress and offers a different approach to defining theme settings, styles, and templates, all from within a single centralized file.

The definitions in theme.json are meant to replace most of the PHP code found in classic WordPress themes and reduce the need for custom CSS. Enqueueing theme assets are also automatically handled for you!

Note: While theme.json is clearly geared towards block themes you can also use it with classic WordPress themes too.

The structure for theme.json is a JSON object with the following top-level properties:

    "version": 1,
    "settings": {},
    "styles": {},
    "customTemplates": {},
    "templateParts": {}

As an example take a look at the theme.json file for the Twenty Twenty-Two theme. This will be the new default theme for WordPress 5.9 when it’s released in December (2021).

It’s quite large so I won’t include the whole file here, but here’s a cut-down snippet showing the custom style overrides for the core button block:

  "version": 1,
  "customTemplates": [],
  "settings": {},
  "styles": {
    "blocks": {
      "core/button": {
        "border": {
          "radius": "0"
        "color": {
          "background": "var(--wp--preset--color--primary)",
          "text": "var(--wp--preset--color--background)"
  "templateParts": []

The styles property allows you to add global styles (for all blocks), and then optionally override them for specific blocks.

As you can see, the entries can be quite complex with multiple nested levels, even for a relatively simple theme such as Twenty Twenty-Two. For more complex themes the theme.json file could become even more unwieldy, making it more difficult to manage and prone to errors.

What if there was a way to edit theme.json content without having to remember all the settings and properties, or constantly referring to the documentation?

Schema Files

Schema files can assist you during the editing process. Let’s be honest, it’s easy for anyone to make mistakes, regardless of their coding level. The schema does all the heavy lifting when it comes to code validation and auto-complete, so there’s no need to remember every supported property, and associated values.

Schema-assisted editing can be a real-time-saver too allowing you to work more in the editor without having to consult external documentation as much.

How Does It work?

The theme.json schema itself is located on along with 100’s of other schema’s. It contains definitions for every possible theme.json valid entry so that it can be checked against your code.

Supported Editors

Many developers will be using VS Code to edit theme.json but schema files are natively supported in many other editors too. The full list is:

  • VS Code
  • PhpStorm
  • IntelliJ IDEA
  • PyCharm
  • Rider
  • RubyMine
  • Visual Studio 2013+
  • Visual Studio for Mac
  • WebStorm
  • JSONBuddy

How Do I Add Schema Support to theme.json?

It’s very simple to add schema support to any block theme. Let’s go ahead and add it to the Twenty Twenty-Two theme. This doesn’t yet include schema support by default (actually, I just added a new issue for this) but it’s pretty simple to add in manually.

Enter this at the top of theme.json, above "version": 1, so it’s the first property:

"$schema": "",

If you’re using VS Code it will automatically recognize the schema file and start parsing the code straight away, highlighting any existing issues. No VS Code extensions are needed here! 🙂

We can now hover over any property to see a tooltip explaining usage.

And auto-complete kicks in whenever you begin typing.

Validation is pretty useful too, making sure entries are in the correct format etc.

It Gets Better – Schema Support for block.json

I was more than happy to know about the schema support available for theme.json files but after taking another look at the block metadata docs I found out that it’s available for block.json files too!

If you’ve created a block plugin using the @wordpress/create-block package then you’ll be familiar with block.json files. It’s the new recommended way to register blocks and define block settings etc.

I’m not sure how I didn’t see the available schema support before. It may be a recent addition to the docs or (more likely) I missed it the first time around. In any case, the block.json schema file gives you a much better editing experience, similar to theme.json. All the same features are available too: tooltips, autocomplete, and schema validation.

Enter this at the top of block.json to enable schema support:

"$schema": ""

Here’s the tooltip working in block.json once schema support has been enabled.

Help Contribute to Schema Files

The theme and block schema files are now part of the Gutenberg repository to make it easier to contribute changes. So, if you spot anything that doesn’t quite look right when editing theme.json or block.json files please consider submitting a pull request or opening a GitHub issue to let the project maintainers know.

Thanks to Birgit Pauli-Haack for pointing out the new repository support for schema files. 🙂

Inner[Block] Thoughts

Schema support for theme.json and block.json is a simple yet very useful addition to block/theme development. And the fact that it’s natively supported in editors such as VS Code is a nice bonus.

I think it’s especially useful as many developers are still finding their feet regarding block, and block theme, development. There’s a lot to take in particularly with theme.json which can quickly grow very large.

The theme.json and block.json files can feel like a bit of a black box at times, not knowing what features are supported or the expected format. Having that little bit of extra assistance means we’re better equipped to edit these files, and that can only be a good thing. Don’t you think?