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:

For example, you should use "$schema": "" 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.

The versions of parent and child themes can be different. You’ll want to take into consideration the same criteria for updating a base theme and follow the same migration instructions for a child themeChild theme A Child Theme is a customized theme based upon a Parent Theme. It’s considered best practice to create a child theme if you want to modify the CSS of your theme. However, there are a couple caveats.

The minimum WordPress version for your child theme will be the highest version between the base theme and your child theme. This means that, even if you don’t update your child theme from version 2, if the parent theme updates to theme.json version 3 and a minimum WordPress version of 6.6, then your child theme will also require the higher minimum version.

If the child theme is version 2 with spacingSizes or fontSizes presets defined and the parent theme is updated to version 3 with defaultSpacingSizes or defaultFontSizes omitted or set to true, then the child theme still won’t show those default presets even though the parent allows them.

  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, @onemaggie, and @askdesign for their assistance writing and reviewing this post.