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

[bph]

Discussed in #256

^{Originally posted by juanmaguitar May 1, 2024}
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]

I'll be writing for this one 👍

[bph]

Thank you, @ajlende
Here are three links for you

• Tips and guidelines for writers
• How to contribute
• Notes on creating and formatting a Google Doc #242

Please let me know how I can assist or if you have questions.

[ajlende]

Sorry this has been taking so long. There have been a few offshoots for other audiences as I was trying to keep this one more focused and short.

• make.wordpress.org/core Dev note for 6.6
• make.wordpress.org/themes Theme.json version 3
• github.com/WordPress/gutenberg Schemas documentation [TODO]

With those mostly out of the way, the Google Docs Draft is finally ready for the first round of reviews.

[justintadlock]

Very well written, @ajlende! The first review is complete. I didn't have much to add, mostly just a few thoughts where things stood out to me while reading.

[bph]

@ajlende I reviewed the post as well. Great post and I learned a ton. I don't have any additional comments.

So if you are ready to post it to the developer blog:
I sent you an invitation to the developer blog, and it should be in the inbox of your ".org profile". Let me know if you have examples code, that needs to be moved to /wptrainingteam organization.

Here are the pre- and post-publishing checklist for your orientation:

Pre-publishing checklist: (updated 1/29/2024)

• Post Title and subheaders in sentence case
• Are Category or Categories selected?
• Are Tags identifies?
• Is there an explicit Excerpt?
• Are all images files uploaded to the media library
• Do all images have an alt-text?
• For TOC us the Pattern under Developer Blog > Table of contents
• Assign or upload a featured image
• Props added? (See Guidelines)
• add copy for a social post as comment to this issue (example)

Save in draft, with Public Post preview enabled.

Post-publishing checklist

• add Props for reviews to #props channel in WP Slack (Example) (use Slack handles)
• Add the label "post to social" to the issue
• close the issue with a comment to link to the published post
• close the accompanying discussion with the link to the published post.

[ajlende]

Alright, I have everything nearly ready. Instead of posting code, I'm going to use WordPress/community-themes as an example. If I ever get a post out about the details of setting it up for yourself written down, I assume we can update this post at that time.

Anyway, public preview is posted at: https://developer.wordpress.org/news/?p=3893&preview=1&_ppp=df7f239fa6

[bph]

@ajlende I conducted a pre-publish review on the post: We are almost there    🎉

📝There are two more to-do items for you, and then you can hit the publish button

1. see below note about the missing link for "Checkout Community themes"
2. And the social post from above pre-publish check list.

I made a few minor changes

• 📝 On the paragraph: "Check out WordPress/community-themes for an example of how to set up automated validation." Is a little thin on how figure it out. I added a link to the Ajv JSON schema validator, but that probably doesn't help. Link to the specific set-up would help  
• I edited the excerpt slightly to make it about WordPress.
• I replaced the theme.json link from the curating the editing experience page to the Global Styles & theme.json page
• Added the link to the blog post on how to register font collection from the developer blog.
• changed PHPStorm to the branded PhpStorm
• added "Language Server Protocol" at the first appearance of LSP
• added "JavaScript Object Notation" to the first appearance of JSON
• added "integrated development environment" to IDE's first appearance

[ajlende]

Thanks for updating the remaining things on the post 🙂

I've updated the links for the community themes; this is what I have now.

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.

I linked both the main repo and the PR adding validation. Maybe only one is needed 🤷

---

Social copy:

Discover how JSON Schema can streamline your WordPress development process. Learn about validating JSON files, configuring your editor, and leveraging key WordPress schemas like theme.json and block.json.

[bph]

🎉 The post is now published: JSON Schema in WordPress

@ajlende Tag you are it for the post-publish checklist if you are up for it.

[ajlende]

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

Thanks for all the help everyone!