How to Use JSON Schema in WordPress Development

When you hear the word “schema”, most immediately think of it as it relates to SEO. Schema in that case helps search engines understand and categorize your webpage content. But as you work with WordPress’ JSON files like theme.json and block.json, there’s another schema that you should pay attention to: JSON schema. With ACF now providing an extended block.json schema with ACF block-specific info, let’s take a closer look at JSON schema, how to leverage JSON schema in your code editor (one line of code!), and the benefits it can bring to your WordPress development process.

What’s JSON Schema?

JSON Schema helps with validation and standardization of JSON files. You know how if you misplace a semicolon in PHP it wants to ruin your life? Well, JSON can be just as picky. One misplaced comma and your entire theme.json file will not be read correctly by the WordPress editor — fun! That kind of troubleshooting is frustrating so it sure would be nice if there’s something that could save you from having to do that by pointing out issues in advance, right? That’s where JSON schema comes in!

By adding one little reference line to the appropriate JSON schema for a JSON file you’re working with, it will help with things like autocomplete, data validation, helpful tooltips, and more. This line points to where your editor can find the data it needs to work its magic on a particular JSON file.

JSON Schema Editor Support

Your code editor needs to be able to read JSON schema in order to get these benefits. Some editors support JSON schema by default, like Visual Studio Code. Others, like Sublime Text, require you install extensions like LSP and LSP-JSON. Odds are, whatever editor you’re using, there is a way to allow JSON schema to be read with an extension or plugin, if it’s not supported out of the box. A quick search of the ol’ Goog with your editor name + “JSON schema” should point you in the right direction.

Setting Up $schema Keys in Your WordPress JSON Files

Once your editor is good to go on reading data from JSON schema, all you have to do is add one line of code to the beginning of your JSON file. So quick! So easy! WordPress provides the $schema locations for theme.json and block.json.

WordPress theme.json $schema:

"$schema": "https://schemas.wp.org/trunk/theme.json"

WordPress block.json $schema:

"$schema": "https://schemas.wp.org/trunk/block.json"

Now, in case there is any doubt over what I mean when I say this line should be placed at the beginning of your JSON file, if your block.json file looked like the following simple example:

{
    "name": "sample-block",
    "title": "Sample Block",
    "description": "An example custom ACF block.",
    "category": "formatting",
    "acf": {
        "mode": "preview",
        "renderTemplate": "blocks/sample-block/sample-block.php"
    }
}

Then, with schema, it would look like:

{
    "$schema": "https://schemas.wp.org/trunk/block.json",
    "name": "sample-block",
    "title": "Sample Block",
    "description": "An example custom ACF block.",
    "category": "formatting",
    "acf": {
        "mode": "preview",
        "renderTemplate": "blocks/sample-block/sample-block.php"
    }
}

Extended WordPress Block.json $schema for ACF Blocks

In the above example, you’ll see it has some keys for ACF. The WordPress default block.json JSON schema will not validate the ACF-specific data as it’s only handling core WordPress block.json info. However, ACF released an extended version of the schema for block.json with ACF block-specific data. You can find that here:

"$schema": "https://advancedcustomfields.com/schemas/json/main/block.json"

If you’re building custom ACF blocks, you may want to use this schema file instead of the regular WordPress block.json one.

JSON Schema is Optional

Adding that one line referencing a JSON schema is all there is to getting the benefits of that sweet, sweet JSON validation. However, will your WordPress development world come crashing down around you if you fail to use JSON schema? No. It’s completely optional. But because JSON can be so incredibly picky, I know I feel like I’ll take all the help I can get when it comes to making sure my WordPress JSON files are in line.

If you’ve overlooked how painfully simple it is to incorporate JSON schema’s validating powers into your WordPress development workflow, hopefully you’ve found this helpful!