Re: [community-group] Add format schema (#360)

> * This schema allows $schema at the root of a design token file while the current technical reports does not allow for it. Should this be kept or removed?

I think we’ll likely revisit the language of the spec. But I think we’d need to keep it, wouldn’t we? Otherwise this couldn’t exist! I think it’s safe for someone opting into JSON Schema, to allow JSON Schema syntax.

> * This schema assumes that the root of a design token file is a group as discussed in [Is the root node of a token tree a standard group? #249](https://github.com/design-tokens/community-group/issues/249). Is that assumption correct?

Yes that’s a safe assumption! We should probably have explicit language; we just never did because why would someone have a design system with 1 and only 1 token (keyword “root”).

We allow for `$ref`s now, which means there may be a _non-root_ node where 1 `.json` file may contain 1 token. But it’s important to consider this case a _partial file,_ i.e. invalid in and of itself, never to be consumed on its own. So yes, the root node should always be seen as a “group.”

> * This schema expects 3 components for all color values, though the specification states "the number of components depends on the color space." Should it be made more accurate to the spec or kept like this for now?

Yes we should allow for any number of components. This is more just future-proofing, because even though the currently-supported colorspaces all _happen_ to have 3 components, we plan on expanding these and in the future, CMYK colorspaces would have 4+. Changing it now would just mean not having to change it later.

> * This schema is currently written for the `draft-07` JSON schema version. Is that the version that should be targeted?

I’m not sure, actually! VS Code seems to have pretty decent 2020-12 support. Are there certain features you opted out of that would be helpful? I think I’d need to understand the tradeoffs a little more. 

> * Should the tests I have written for the schema also be included in the PR or just the schema?

That would be great! We use [Vitest](https://vitest.dev) in this repo, so as long as they are convertible to that, that would be a great addition.

> * Does this schema work with the arbitrarily-nested DTCG files issue mentioned in [feat: Add JSON Schema for resolver documents #356](https://github.com/design-tokens/community-group/pull/356)?

I was not able to easily test it because of the absolute `$ref` URLs that point to files that don’t yet exist. I left this comment elsewhere, but could we try relative URLs, at least for testing? I have several documents in [dtcg-examples](github.com/terrazzoapp/dtcg-examples) I could test them on.

-- 
GitHub Notification of comment by drwpow
Please view or discuss this issue at https://github.com/design-tokens/community-group/pull/360#issuecomment-3620745747 using your GitHub account


-- 
Sent via github-notify-ml as configured in https://github.com/w3c/github-notify-ml-config

Received on Saturday, 6 December 2025 17:32:14 UTC