How JSON schema versioning works and how it's different from the theme.json version

[juanmaguitar]

Based on feedback like this one

https://twitter.com/ChrisHufnagel/status/1784316768393052284

It would be useful for developers to have an additional explanation about how JSON schema versioning works and how it's different from the theme.json version.

Such an article should cover IMO, at least the following ideas:

• JSON Schemas for block.json and theme.json
• The benefits of using a JSON Schema
• Which JSON Schema version (which URL) should I use for my project?
• What's the purpose of the version property in a theme.json?
• What's the relationship (and differences) between the version of the JSON Schema and the version of the theme.json?
• What's the purpose of the version property in a block.json? Is it related to the version property in a theme.json?

@ajlende is on board about writing a post about this topic (see this comment)

It's confused often enough that I'm planning on writing a developer.wordpress.org blog post to help explain how JSON schema versioning works and how it's different from the theme.json version.

[ajlende]

The reason this is more relevant now is that the latest theme.json version has been incremented as of WordPress/gutenberg#58409. Anyone using the Gutenberg plugin or a minimum version of WordPress 6.6, when it is released, for their theme should update to use the latest theme.json version as new features are only developed on the latest version.

Most themes, however, do not require the Gutenberg plugin or a minimum version of WordPress 6.6, so they should not be updating to version 3 just yet. All previous versions of theme.json are backwards-compatible on the latest version of WordPress and the Gutenberg plugin.

The source of confusion I'm seeing is folks using the https://schemas.wp.org/trunk/theme.json version of the schema. A lot of the documentation for JSON schema has used trunk as an example, so many themes (including default themes) are using the trunk schema version when they should probably be using a tagged WordPress version instead. For example, https://schemas.wp.org/wp/6.5/theme.json, is the schema to use if you are targeting 6.5 as your minimum WordPress version.

Anyone who is using the trunk version of the schema for validation, either in their editor or with another tool, will see a warning that 2 is no longer a valid version. Rather than updating the theme.json version, though, it would be better for them to update the schema version to match their minimum supported WordPress version.

The living theme.json reference which @juanmaguitar is referencing in the twitter post is generated based on the trunk version of the schema. The theme.json version 2 reference is still available for anyone still using theme.json version 2 for WordPress 5.9–6.5, and the theme.json version 1 reference is available for anyone still supporting WordPress 5.8.

[zzap]

Can we also discuss blueprint.json for Playground? Just to make sure that people who have never heard about it do.

[ajlende]

I'm one of those who isn't familiar with blueprint.json, so I'll have to look it up. Thanks for the suggestion 👍

[bph]

The topic was approved 5/2/24 and the conversation continues on the issue

• How JSON schema versioning works and how it's different from the theme.json version #260

[ajlende]

Published at https://developer.wordpress.org/news/2024/07/19/json-schema-in-wordpress/

Thanks for all the help everyone!

[bph]

Thank YOU for your great work on the article!