Re: [community-group] Proposal: JSON Schema $ref for aliases (breaking change) (#259)

Hi all, I've discovered this specification in my exploration of building a unified design token linter/code generation tool (apologies, I've embarked on this before discovering the prior art!) I hope you don't mind me dropping in with some comments, from an outsider perspective.

Reading through this, and the wider spec as it currently exists, I see lots of things borrowed from JSON Schema. It seems a lot of effort is going into discussion of schema internals e.g. multi-file references, handling edge cases. These are totally valid points, but they make me question: why are we inventing our own bespoke referencing and validation mechanism at all?

There are established, well-designed specifications for describing and linking JSON documents - JSON Schema being one we appear to be re-implementing indirectly here. They already define things like `$ref`, syntax, remote references etc. Rather than debating precise schema implementation details like whether to escape `/`, could we not simply choose an existing superset and adopt it wholesale? We can then focus energy on the aspects of this spec that are domain-specific i.e. design tokens.

In practise, this might look like:

- **Picking a base spec**: e.g. we might decide a design token file is a JSON document validated by JSON Schema. We might decide it's JSON Pointer syntax. The point is not which one we choose, but that we don't design our own.
- **Reference, not replicate**: we should avoid re-implementing existing specs, or straying outside our domain (design token interchange format).

I think we should decide how coupled we want the specification to be to existing tooling. We should avoid artificially limiting the robustness of this specification because migration may be difficult for downstream consumers. There are no legitimate downstream consumers yet, this specification is not final. There is still time to make a clean break.

My concern is that we seem to be spending time debating custom syntax and validation when those concerns are orthogonal to design tokens themselves. The scope of this group is to define a **design token interchange format**, not to create a new flavour of JSON. Using an existing JSON superset would let us stand on existing tooling and remain focused on our raison d'etre.

Thanks again for the work you're doing here, I am here also because I've encountered the pain this group is trying to solve. I hope you take my drive by commentary in good faith! 

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


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

Received on Saturday, 13 September 2025 13:11:28 UTC