Using Schema with WordPress theme.json

Learn how using schema with a WordPress block theme’s theme.json file can help you write code efficiently and precisely.

Learning outcomes

  1. Explain the benefits of using schema with a theme.json file.
  2. Utilize schema to write, modify, and edit json code.

Comprehension questions

  1. What are the four main benefits of using schema with theme.json?
  2. How can schema help designers create block themes?


Welcome to using schema with WordPress theme.json. Let’s get started. First, what is schema? Json schema is a vocabulary that allows you to annotate and validate json documents. In other words, it helps you to write code with confidence. In order to use schema successfully, you’ll need a text editor that works with it such as Visual Code Editor, which is pictured here or another, such as Eclipse or PHP Storm. Let’s see how it works.

Schema is made up of two lines that you add to the top of your theme or child themes theme.json file. First, I’m going to add the schema line to this theme.json file. Now that I’ve added the schema line, it’s telling my code editor that this file has a specific set of rules that can be applied to it so that it can do a few things for us.

First, it can autocomplete for us. If I remove this version, and I started a new line, I’ll start by opening up the quotes. Now the schema will tell me what my options are for this line. The only thing available that isn’t already present in this file on this level is version, which is the version of the schema. If I hit enter, now, it will fill in the rest of the line for me; it put in version, close the quotes, add the colon, and it added the value. The only value we should use here is two, which as of this recording is the most recent version of schema. There is an earlier version, but this should recommend the current version to you.

Now let’s watch this magic work under “Settings” next. In this instance, things that are available but not already used in this theme are blocks and borders. Schema is maintained by the core development team, so it should stay updated.

What else can schema do? Well, schema can also tell you if you make a syntax error. For example, if we remove this comma, it says, “Oh, this doesn’t look right.” If I hover over it, it will sometimes give me a clue as to what I did wrong. If I add the comma back, the squiggly lines go away. Finally, if you hover over these different objects, you will see some tooltips, which is inline documentation to go along with each of these things. You can see which customization options are available default colors, CSS custom properties and the default layout of the editor. Let’s see this again. If I hover over the section custom templates, it gives a little more information about this section. Pretty cool, right?

That’s the short version of how you can use schema with WordPress theme.json file. In short, schema helps you write code by providing suggestions of what’s available in each theme.json setting, auto completing your code with available options, alerting you to errors and providing more information such as hints as to what could be wrong and what each section might do. We hope you have fun experimenting with this fantastic feature.

Workshop Details


Sarah Snow

WordPress educator and/or mad scientist; my professional hobbies include breaking WordPress websites in front of audiences, investigating simple solutions to odd problems collaboratively, and designing lesson plans and courses for Ask me about caring for parrots, training stubborn Shar Peis, cooking super spicy recipes, learning American Sign Language & French, teaching and writing. Changing the narrative one story at a time.

Other Contributors

Daisy Olsen