Theme.json version 3 frequently asked questions

WordPress 6.6 contains some updates to theme.jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. including a new version and associated schema.

The theme.json version is incremented whenever a breaking change needs to be made to the APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways.. This allows consumers to opt-in to the breaking change by updating the version. Older theme.json versions will always be supported in the latest versions of WordPress.

You are probably not using the correct theme.json schema version. Use the schema version that matches your minimum supported WordPress version.

The WordPress release versions of the schema follow the pattern: https://schemas.wp.org/wp/x.y/theme.json.

For example, you should use "$schema": "https://schemas.wp.org/wp/6.5/theme.json" in your theme.json if the minimum supported WordPress version for your theme is WordPress 6.5.

They are used for different things.

The theme.json version is what WordPress uses to handle backward compatibility. It keeps your theme looking the same in newer versions of WordPress even if the names of properties change, defaults changes, or other breaking changes are added in a new version.

The schema version is what your editor uses to tell you if you’re doing something wrong in your theme.json. It’s tied to the WordPress version so it can keep track of which features are available in each version of WordPress. This means that you can specify which version of WordPress you want to support and only the theme.json features from that version will show up in autocomplete and be validated as correct in your editor.

Probably not yet.

Version 3 theme.json will require a minimum version of WordPress 6.6, so if you update your theme to use version 3, you will need to specify 6.6 as the minimum version of the theme.

When you want to use new theme.json features from WordPress 6.6 or later and are okay with bumping the minimum WordPress version for your theme to support them, then you can migrate your theme.json to version 3.

  1. Follow the instructions in the theme.json reference guide for migrating v2 to v3 to update your theme.json.
  2. Remember to update the minimum version of your theme to WordPress 6.6 or later.

For new themes, it’s probably best to use the new version of theme.json, as long as you are happy that only users on WordPress 6.6 or higher will be able to use your theme.

Props @scruffian and @onemaggie for helping write and review this post.