Theme Export: If the theme declares a version number then add a schema #39775

scruffian · 2022-03-25T20:42:49Z

What?

Add a $schema key to theme.json if it declares a version.

Why?

If we know the version of the theme.json then we can add a $schema to improve developer experience.
Fixes #39575

How?

We detect the version of the theme.json and then add a $schema attribute if it's present. In the future we'll need to change the schema depending on the version.

We do array_reverse on the data so the $schema gets added to the start of the theme.json file, not the end.

Testing Instructions

Switch to a block theme
Go to the site editor
Export your theme
Verify that the zip file contains a theme.json file which contains a $schema attribute

Screenshots or screencast

cc @WordPress/block-themers

mikachan

This works well for me when I export a theme!

I've just left one comment about the schema URL.

mikachan · 2022-03-26T12:10:10Z

lib/compat/wordpress-6.0/block-template-utils.php

+	if ( $theme_json_raw['version'] && in_array( $theme_json_raw['version'], array( "1", "2" ) ) ) {
+		// Put $schema at the start of the array.
+		$theme_json_raw = array_reverse( $theme_json_raw );
+		$theme_json_raw['$schema'] = "https://json.schemastore.org/theme-v1.json";


Would it be better to use this URL: https://schemas.wp.org/trunk/theme.json?

I think this one is always kept up to date with Gutenberg, based on this post.

oandregal · 2022-03-28T08:54:41Z

lib/compat/wordpress-6.0/block-template-utils.php

@@ -99,10 +99,18 @@ function gutenberg_generate_block_templates_export_file() {
 	// Load theme.json into the zip file.
 	$tree = WP_Theme_JSON_Resolver_Gutenberg::get_theme_data();
 	$tree->merge( WP_Theme_JSON_Resolver_Gutenberg::get_user_data() );
+	$theme_json_raw = $tree->get_data();
+	// If a version is defined, add a schema.
+	if ( $theme_json_raw['version'] && in_array( $theme_json_raw['version'], array( "1", "2" ) ) ) {


The issue with checking for 1 or 2 is that when the version is upgraded this code needs to as well. Given that worst-case scenario is that the schema is not yet published, hence is ignored by editors, can we use what's in version? version is going to be always the latest, and, except for perhaps the dates around a major WordPress release it's going to be already published in the schema store.

Hmmm, but https://json.schemastore.org/theme-v2.json doesn't exist?

Oh, interesting. I just saw Sarah's comment above #39775 (comment) pointing to https://make.wordpress.org/themes/2021/11/30/theme-json-schema/

According to that, it sounds like we need to use different URL depending on whether we run in the plugin or core. I'll ping @ajlende for confirmation but it seems that we need:

https://schemas.wp.org/trunk/theme.json in the plugin

https://schemas.wp.org/wp/<version>/theme.json in core

We need to do something to remember doing the change when this code is ported to core. Perhaps a comment would sufice.

scruffian · 2022-03-28T11:56:22Z

I updated the approach here to use the URLs above, including the trunk one for when Gutenberg is installed.

carolinan · 2022-04-01T05:14:10Z

There is an edge case, and I wouldn't recommend it, but if for any reason, the active theme has set version: 1 and schema to 5.8, then the export changes this to trunk and version 2:

{
	"$schema": "https://schemas.wp.org/wp/5.8/theme.json",
	"version": 1
}

(as copied from https://make.wordpress.org/themes/2021/11/30/theme-json-schema/)

Becomes:

{
    "$schema": "https://schemas.wp.org/wp/trunk/theme.json",
    "version": 2,
    "settings": {
        "color": {
            "custom": true,
            "customGradient": true
        },
        "typography": {
            "customFontSize": true,
            "lineHeight": false
        },
        "spacing": {
            "units": false,
            "padding": false
        }
    }
}

draganescu · 2022-04-05T09:42:48Z

lib/compat/wordpress-6.0/block-template-utils.php

+			$theme_json_version = 'trunk';
+		}
+		$theme_json_raw = array_reverse( $theme_json_raw );
+		$theme_json_raw['$schema'] = 'https://schemas.wp.org/wp/' . $theme_json_version . '/theme.json';


Can't $schema already exist? if it's added manually we should respect that.

It's not stored in the tree - we could get it from the file directly, which is the approach I took at first (#39590) but it seems like the recommended approach is to use the data from the class instance rather than getting it from the file, so it's properly sanitised etc.

Should WP_Theme_JSON_Schema_Gutenberg handle the URL of the schema, since this class is in charge with migrating existing JSON to new versions, then it is the ultimate source of truth for what schema is in use.

cc @oandregal

draganescu

I think this is a good approach considering we want this to only serve as a dev ex improvement.

I wonder if theme.json will be exposed via REST maybe the schema will become handy then? The fact that if I define a schema and version in my theme.json they'll be overwritten on export, doesn't seem to count for anything, since we do

$this->theme_json = WP_Theme_JSON_Schema_Gutenberg::migrate( $theme_json );

right in WP_Theme_JSON's constructor. Also, on export, the schema is taken from the current environment, as if it is a custom property and

The custom's has higher priority than the theme's, and the theme's higher than defaults's.

Whatever we think of doing in the future, I can't see this addition blocking it.

oandregal · 2022-04-06T15:50:10Z

lib/compat/wordpress-6.0/block-template-utils.php

+		if ( defined( 'IS_GUTENBERG_PLUGIN' ) ) {
+			$theme_json_version = 'trunk';
+		}
+		$schema         = array( '$schema' => 'https://schemas.wp.org/wp/' . $theme_json_version . '/theme.json' );


Considering the convo where we talked about this, I've noticed that this code returns:

https://schemas.wp.org/wp/trunk/theme.json in the Gutenberg plugin: shouldn't it return https://schemas.wp.org/trunk/theme.json instead?

It contains the patch version as in: https://schemas.wp.org/wp/5.9.3/theme.json when running on WordPress versions with patch versions (all of them but 6.0). Shouldn't it return https://schemas.wp.org/wp/5.9/theme.json instead? Note that the Gutenberg branches that host the schema don't have the minor: 5.9, 5.8.

cc @scruffian @draganescu

Thanks for that. There's a fix here: #40106

scruffian added the [Feature] Themes Questions or issues with incorporating or styling blocks in a theme. label Mar 25, 2022

scruffian requested review from TimothyBJacobs and spacedmonkey as code owners March 25, 2022 20:42

scruffian self-assigned this Mar 25, 2022

scruffian mentioned this pull request Mar 25, 2022

Theme Export: Add missing properties to theme.json #39590

Closed

mikachan reviewed Mar 26, 2022

View reviewed changes

oandregal reviewed Mar 28, 2022

View reviewed changes

scruffian force-pushed the udpdate/theme-export-schema branch from 1ee77d1 to 29b0e66 Compare March 28, 2022 11:32

scruffian mentioned this pull request Mar 28, 2022

Exporting Block Themes and Styles #27941

Closed

ajlende self-requested a review April 1, 2022 05:18

draganescu reviewed Apr 5, 2022

View reviewed changes

scruffian force-pushed the udpdate/theme-export-schema branch from 2d61f24 to 7586a4c Compare April 5, 2022 09:57

scruffian added 2 commits April 5, 2022 10:59

Theme Export: If the theme declares a version number then add a schema

62d2daa

use array merge instead of array_reverse

c46de20

scruffian force-pushed the udpdate/theme-export-schema branch from 7586a4c to c46de20 Compare April 5, 2022 13:34

draganescu approved these changes Apr 5, 2022

View reviewed changes

fix linter

f1a3953

scruffian merged commit 3c05374 into trunk Apr 5, 2022

scruffian deleted the udpdate/theme-export-schema branch April 5, 2022 16:49

github-actions bot added this to the Gutenberg 13.0 milestone Apr 5, 2022

oandregal reviewed Apr 6, 2022

View reviewed changes

scruffian mentioned this pull request Apr 6, 2022

Theme Export: Change the schema url #40106

Merged

bph mentioned this pull request Apr 7, 2022

Dev Notes Tracking Issue for WordPress 6.0 #39654

Closed

37 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Theme Export: If the theme declares a version number then add a schema #39775

Theme Export: If the theme declares a version number then add a schema #39775

scruffian commented Mar 25, 2022

mikachan left a comment

mikachan Mar 26, 2022

oandregal Mar 28, 2022 •

edited

Loading

scruffian Mar 28, 2022

oandregal Mar 28, 2022

scruffian commented Mar 28, 2022 •

edited

Loading

carolinan commented Apr 1, 2022

draganescu Apr 5, 2022

scruffian Apr 5, 2022

draganescu Apr 5, 2022

draganescu left a comment

oandregal Apr 6, 2022

scruffian Apr 6, 2022

Theme Export: If the theme declares a version number then add a schema #39775

Theme Export: If the theme declares a version number then add a schema #39775

Conversation

scruffian commented Mar 25, 2022

What?

Why?

How?

Testing Instructions

Screenshots or screencast

mikachan left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

oandregal Mar 28, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

scruffian commented Mar 28, 2022 • edited Loading

carolinan commented Apr 1, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

draganescu left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

oandregal Mar 28, 2022 •

edited

Loading

scruffian commented Mar 28, 2022 •

edited

Loading