Reserve top-level $schema property?

[natemoo-re]

Visual Studio Code supports a top-level $schema property which provides their JSON Language Server with automatic completions, hovers, etc. While it is not part of the JSON Schema specification, it is a feature that I see being used with increasing frequency. See schemastore.org for examples of tools which have public schemas.

IMO calling this property out in the specification would be wise, even just as something that tools should accept but ignore. I've definitely encountered tools that have trouble validating or parsing a JSON file when $schema is used and it can be a pain.

[natemoo-re]

While we're on the topic of JSON Schema, I started working on a public schema that aligns with much of the current draft. My current version is a little more opinionated in group structure than the spec, but I'm sure the token definitions are still useful.

I'm happy to contribute to an official spec schema if there's interest!

[TravisSpomer]

Definitely agree with this. The token format is currently missing some kind of versioning field anyway, and $schema could potentially even be used for that purpose too, though I'm not entirely sure if that's wise.

[c1rrus]

I agree this could be useful and could double as a versioning field (something we've been meaning to add anyway). We could have the spec version that the file conforms to as part of the URL to the corresponding schema. E.g.:

{
  "$schema": "https://designtokens.org/spec/v1.2.3/schema.json",
  // ^ This file follows version 1.2.3 of the DTCG spec

  // tokens and groups go here as per usual
}

I also agree that having a JSON schema for our spec could be useful. It would allow some basic validation of files and can enable some auto-completion features in some IDEs. It's something that's been suggested before and has been discussed at previous editors meetings too. We've just not gotten around to properly exploring the topic yet. When we do, I'm sure @natemoo-re's schema will be a valuable input, so thanks for sharing that!

Also, since we've now decided to use $ as our prefix for all format-specific properties, this would fit in nicely with that :-)