JSON Schema in WordPress

As a WordPress developer, you’ve likely encountered files written in JavaScript Object Notation (JSON) in various aspects of your work. Maybe you’ve defined custom blocks, configured a theme, or set up a local development environment. Have you ever wished for a way to ensure you’re using the correct options for these configuration files? That’s where JSON Schema comes in. Let’s explore how this tool can help you catch errors early and streamline your development process.

What is JSON Schema?

JSON Schema sets the rules for how JSON data should look. It lets you define what types of values are expected, which fields are required, and any other constraints on the data. JSON Schema is a contract between those who create the data and those who use it, making it easy to understand the data structure and automatically check that the JSON content is correct.

JSON Schema has different schema versions called “meta-schemas” as they are schemas for writing schemas. Most editors and integrated development environments (IDE)s support http://json-schema.org/draft-07/schema# (Draft 7), but in some cases, you may need to use a different meta-schema if Draft 7 isn’t supported.

Why use JSON Schema?

Imagine you’re working on a project with a complex configuration file in JSON format. Without a schema, you might find yourself constantly referring to documentation or previous examples to remember what properties are allowed where. This is where JSON Schema shines:

1. Autocomplete and IntelliSense: Many modern IDEs and text editors can use JSON Schema to provide intelligent autocomplete suggestions as you type.
2. Documentation: The schema itself serves as a form of documentation, describing the structure and constraints of your JSON data.
3. Validation: JSON Schema can automatically validate your JSON data, catching errors before they cause issues in your application.
4. Automated testing: You can use JSON Schema in your automated tests to ensure that your JSON data always conforms to the expected structure.
5. API Design: When designing APIs, JSON Schema can help you clearly define the structure of request and response bodies.

By leveraging JSON Schema, you can write more accurate code, catch errors early, and accelerate your development process. It’s especially valuable in larger projects or when working in teams, as it ensures consistency across different parts of a project.

Validating JSON files

The best place for JSON validation is in your code editor or IDE. Not only will your JSON file be checked for correctness as you are writing it, but many editors support autocomplete based on properties in the JSON Schema. Let’s go through how to set up your editor to use JSON Schema.

JSON files with a $schema property

The most common way to specify a JSON Schema version is with the $schema property. All WordPress schemas support the $schema property for specifying a specific schema version to validate against.

Many WordPress schemas are versioned alongside major wp/x.y WordPress releases. They also have a trunk version with all the latest development changes coming to a future version of WordPress. We’ll cover these schemas later.

Usually, you’ll want to match your schema version to the minimum supported WordPress version for your theme or plugin.

{
  "$schema": "https://schemas.wp.org/wp/x.y/schema.json"
}

JSON files without a $schema property

Occasionally, a JSON file you’re working with won’t have a $schema property. What should you do then?

Many editors allow you to manually set a schema for matching file names. This way you can associate a specific schema version with a file or set of files. Dive into your editor’s documentation to find out how to configure this—it’s often just a matter of tweaking a few settings.

But what if you would rather not configure each one manually and aren’t concerned about using a specific schema version? That’s where the JSON Schema Store catalog comes to the rescue. The catalog includes many common JSON schemas including WordPress schemas. Once set up, your editor can fetch and apply schemas from the catalog automatically.

Configuring your editor

Most code editors have some form of support for JSON schema. Try using the $schema property or checking your editor’s documentation. Here are some details for popular editors used by WordPress developers.

Visual Studio Code (VS Code)

VS Code works out-of-the-box with the $schema property. To use the JSON Schema Store catalog, install the JSON Schema Store Catalog extension.

See the Visual Studio Code documentation for additional configuration options.

PhpStorm and JetBrains IDEs

JetBrains IDEs like PhpStorm, WebStorm, and IntelliJ IDEA work out-of-the-box with the $schema property and the JSON Schema Store catalog.

See the JetBrains documentation for additional configuration options.

Sublime Text

Sublime Text doesn’t have built-in JSON Schema support, but you can use the Language Server Protocol (LSP) and LSP-json packages to get $schema property and JSON Schema Store catalog support:

1. Install Package Control if you haven’t already.
2. Install the LSP and LSP-json packages from Package Control.
3. Restart Sublime Text.

See the Sublime Text documentation and LSP-json homepage for additional configuration options.

Automate validation in your projects

Using editor integration is useful when working by yourself, but if you’re working with multiple collaborators you might want to add some automation checks to ensure that everyone is following the schema.

Ajv JSON schema validator has Node.js packages for validating schemas. Check out WordPress Community Themes for an example of how to add automated validation.

JSON schemas in WordPress

WordPress uses several JSON schemas to configure different aspects of themes, plugins, and development. Here are the key schemas available:

theme.json

https://schemas.wp.org/wp/x.y/theme.json

The theme.json file is used to configure a WordPress block theme. It allows theme developers to define styles, settings, presets, and variations for their themes in a structured and consistent manner. Key features include:

• Editor settings: Control various settings, such as enabling or disabling features like custom colors, gradients, and font sizes.
• Custom presets: Define custom variables for use within global styles, such as color palette presets, gradient presets, and spacing presets.
• Global styles: Define typography, colors, spacing, and other styles that apply across the entire theme.
• Variations: Separate files located under the /styles folder that contain partial overrides for the main theme.json.

For more information, refer to Global Styles & theme.json documentation.

block.json

https://schemas.wp.org/wp/x.y/block.json

The block.json file is used to configure custom blocks for the Gutenberg editor. This schema allows developers to define block properties and settings in a structured format. Key features include:

• Registration: Defines essential block properties like name, title, category, and icon for easy registration.
• Attributes: Details custom attributes to manage block data and functionality.
• Supports: Indicates feature support to add to the block, such as alignments, color, HTML editing, and more without having to write extra code.

For more information, refer to the block.json guide.

font-collection.json

https://schemas.wp.org/wp/x.y/font-collection.json

The font-collection.json schema is used for registering custom font collections in WordPress. This is particularly useful for themes and plugins that require specific fonts. Key features include:

• Font Family: Define the name of the font family.
• Font Variants: Specify the different styles and weights available within the font family.
• Source: Provide the source URL or path for the font files.
• Licensing: Include information about the font’s licensing to ensure compliance.

For more information, refer to the font-collection.json guide. To learn more about, read How to register custom font collections for the Font Library

wp-env.json

https://schemas.wp.org/trunk/wp-env.json

The wp-env.json file is used for configuring local WordPress environments, primarily for development and testing purposes. This schema helps in setting up a consistent environment across different machines. Key features include:

• WordPress Version: Specify the version of WordPress to use in the environment.
• Plugins and Themes: List the plugins and themes to be included in the environment.
• Environment Variables: Define environment-specific variables to customize the setup.
• Docker Configuration: Configure Docker settings if using Docker for the local environment.

For more information, refer to the wp-env.json documentation.

blueprint.json

https://playground.wordpress.net/blueprint-schema.json

The blueprint.json schema is similar to wp-env.json but is used specifically for the WordPress Playground. This schema helps in setting up and configuring WordPress instances for educational and experimental purposes. Key features include:

• Configuration: Define the setup parameters for the Playground environment.
• Resources: Specify the resources, such as themes and plugins, to be included.
• Environment Setup: Customize the environment settings for the Playground instance.

For more information, refer to the blueprint.json documentation.

WordPress REST API

While the schemas we’ve discussed so far are used primarily for configuration, JSON Schema plays a different role in the WordPress REST API.

If you are developing a REST API endpoint you can use JSON Schema to:

1. Validate request data: When data is sent to an API endpoint, it’s validated against the schema before being processed.
2. Provide client-side validation: The schema is used to automatically generate OPTIONS endpoints for the API that can be queried for the supported HTTP methods and structure of a request.

For more information, see the documentation for extending the REST API.

Contributing to WordPress JSON Schemas

WordPress JSON Schemas are open for contributions. You can contribute by making pull requests to the Gutenberg repository.

Read through the WordPress schemas README to see how to contribute.

Props to @onemaggie, @scruffian, @jeryj, @juanmaguitar, @ndiego, @greenshady, @bph, and @milana_cap for their suggestions and help with this post.