theme.json can't have comments

[iandunn]

What problem does this address?

theme.json is a configuration file maintained by humans, rather than a data-interchange file used by software. Comments are an essential feature of any configuration file, in order to document important decisions, explain things that aren't obvious, etc. For example:

"settings": {
		"spacing": {
			"//blockGap": "The design calls for a 24px gap. Coincidentally, that's the default value that Gutenberg defines. The default could change in the future, though, so this should be explicitly set.",
			"blockGap": "24px",

JSON tooling usually (and mistakenly) doesn't allow comments, though. Many tools will strip them out, or just fail to run. There are lots of workarounds, but the half dozen I've tried have all had significant downsides. For example:

"settings": {
		"custom": {
			"alignment": {
				"//alignedMaxWidth": "Foo bar blah blah blah...",
				"alignedMaxWidth": "50%"
			},

...results in:

--wp--custom--alignment----aligned-max-width: Foo bar blah blah blah...;

What is your proposed solution?

Consider using JSON5 instead of JSON. It's a superset, so there aren't any back-compat issues.

If that's done, we'll need to document it, otherwise devs will assume they can't use comments and miss out on the benefits.

[glendaviesnz]

Is adding a schema link into theme.json an alternative approach to comments? eg. "$schema": "https://json.schemastore.org/theme-v1.json", @ajlende has started a theme.json schema already at https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/theme-v1.json which I believe can be extended to add descriptions to all of the fields, which when used with an IDE that supports it will show tooltips to developers.

[brownboycodes]

you can also write ✍🏽 the configuration files 📝 in YAML and convert it to JSON with tools like https://www.json2yaml.com/convert-yaml-to-json

YAML is also a superset of JSON and uses python 🐍 like line separation & indentation and commenting with # comment, and its as easy as JSON

theme configuration file in YAML

settings:
  spacing:
    # blockGap: "The design calls for a 24px gap. Coincidentally, that's the default value that Gutenberg defines. The default could change in the future, though, so this should be explicitly set."
    blockGap: 24px
  custom:
    alignment:
      # alignedMaxWidth: Foo bar blah blah blah...
      alignedMaxWidth: 50%

the equivalent JSON code converted from YAML with https://www.json2yaml.com/convert-yaml-to-json

{
  "settings": {
    "spacing": {
      "blockGap": "24px"
    },
    "custom": {
      "alignment": {
        "alignedMaxWidth": "50%"
      }
    }
  }
}

[iandunn]

I think those are both good workarounds, but not ideal solutions.

Maintaining a fork of the canonical schema would be too much work for the benefit you'd get IMO, could lead to things being out of sync and inaccurate, and tooltips are really easy to miss.

I think having to setup and run extra tooling would also add more pain than it'd remove. Tooling often breaks, someone might manually modify the .json file and then lose those changes, etc.

I think using YAML directly is worth considering, though, instead of JSON5. It might come down to which has a more reliable PHP parser.

[Enchiridion]

I would also like to see the default format changed. Between JSON5 and YAML, I'd strongly prefer YAML. It's much easier for humans to read/write, no commas or quotes to worry about.

I tried using the $schema with JSON, but it leaves a lot to be desired. I just created a YAML version of theme.json and documented it (including the new/experimental stuff that's missing from $schema) for the other developers at my company and added it to my webpack build/watch tasks to convert it back to JSON. I save it as a single line of text and don't pretty print it so anyone who opens theme.json will realize it's a generated file. It works, I'm happy with it, but would still prefer native support.

YAML parsers are available for just about every language and are fast. Going forward theme.json could be deprecated and only loaded if theme.yaml isn't present.

[theMikeD]

Using a file format that doesn't provide for comments is frankly indefensible.

[danzinger]

I strongly recommend using YAML instead of JSON for the theme file. As others have stated this can easily be converted to a JSON Object for internal use. But to read and write for humans it is much nicer. Also we could write comments, which is good practice and should be standard when writing themes. We should not encourage authors to write uncommented code.

In case sombody is interested: Personally I use a setup where I convert a theme.yaml to theme.json on every save. I use remarshal for the conversion. I have language-server support including schema support in VIM when writing the theme.yaml using coc and the coc-yaml extension.

[roryashfordbentley]

+1 for YAML.

One of the biggest barriers for developers new to FSE and Hybrid themes is understanding what and why things exist in theme.json. As a developer on the project I have a responsibility to leave comments for the team and at the moment these are either added to a seperate readme or are discussed ad-hoc on Slack, neither are ideal and both get lost over time.

[landwire]

Hi there,
as the theme.json is getting more and more complex and the single source of truth, I created a plugin called Theme Yaml. Exactly for the same reasons that have been discussed in this threat.

It's very simple and converts an existing theme.yaml file to theme.json. Basically it's for people who know what they are doing and obviously you should not touch the theme.json file manually.

You can find it here: https://wordpress.org/plugins/theme-yaml/
Leave some feedback on the plugin please, if you find it useful and it works for you :-)
Thanks!

[landwire]

But obviously I would prefer if theme.yaml would be supported by core Wordpress and not via a plugin/workaround.

[SamuelMiller]

This appears to work in theme.json: One way is using adding key-value pairs with comments and description JSON always contains data of key and values, so add comments key in json object with value is a comment string value.

{
"key": "value",
"comments":"One way to write comments here"
}

More here: https://www.w3schools.io/file/json-comments/

Also how about the newer JSON5 which allows comments: https://json5.org/

[scruffian]

In #34180 we added comments like this

{
"//": "This is a comment",
"key": "value"
}

[iandunn]

I've tried that workaround in other contexts, but they're often removed by encoders because they're duplicate and/or invalid keys (e.g., package.json). There may not be any encoders for theme.json yet that would cause a tangible problem, but there easily could be in the future.

My IDE also adds an inspection warning because of the duplicate key. If you disambiguate it with something like //key1, then WP creates invalid CSS vars (see the issue description).

It's an ok workaround for now, but I think it'd be much better to solve the root issue instead.

[onetrev]

That's great news @scruffian. However, is you the WP JSON scheme (which is very handy, nearly essential to use I think), your IDE will report errors with your theme.json if you add a comment that way. :(

[scruffian]

@onetrev That style of comment isn't valid for theme.json yet, only for block.json, for now.

[onetrev]

For anyone considering YAML, if you are VS Code person, then I've found this work flow to be pretty smooth. And it has working schema support for error checking!

Add a YAML language server to enable schema support. Then add a YAML to JSON converter. Job done. You have comments, schema error checking, and your brain won't explode by trying to work with a huge JSON file. :)

The only thing missing is having different parts of the main YAML / JSON file coming from different source files. That would be the nirvana solution for sure.

[onetrev]

I've noticed for a while that comments are now allowed in theme.json files, like so:

"spacing": {
        "//": "Global gap spacing uses existing spacing preset value",
        "gap": "var(--wp--preset--spacing--20)"
      }

So can we now close this issue @iandunn / @scruffian?

[theMikeD]

This feels like a hacky work-around for a poor decision, but if this is all we have left then this issue should not be closed until this information appears in the appropriate documentation for this file.