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

> @brettdorrans Thanks for your feedback! I think we are aiming at the same things overall.
> 
> > 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.
> 
> This is a proposal to align DTCG spec around exactly what you specified—existing standards and prior art. This quite literally adopting part of JSON Schema. Would you say you are in favor of this proposal to the spec? Or are you saying “we should have started here in the first place?”

Hey @drwpow - thank you for your efforts on this project. Apologies if my comments were unclear. I'm glad to hear the goal is to align with existing standards, and I appreciate this PR moves further towards that goal.

I do support adopting JSON Schema's syntax and pointer semantics as part of the spec, but I think we should go further. Right now this PR focuses on introducing `$ref` for aliases. My view is that the design token format shouldn't reinvent JSON-Schema-kike features piecemeal; instead a better approach may be:

- Adopt JSON Schema across the entire spec, not adopt parts of JSON Schema or reimplement its pointer system. 
- Use `$ref` universally, not just for `$value` - if we adopt JSON Schema holistically, we can allow tokens to reference arbitrary parts of other tokens (or documents) in future. We open up a lot more interoperability this way. We shouldn't need to define what an alias is or how `$ref` works - we should point to JSON Schema docs.
- Avoid re-implementing validation logic or enforcing this too tightly in the spec - JSON Schema tooling already handles remote references, recursion, circular‑reference detection, etc. If we fully embrace it, tool authors can use existing libraries instead of writing custom resolvers for DTCG‑specific syntax (this is the worst case scenario imo!)

I appreciate that this PR is trying to align DTCG with prior art. From my perspective it's a good start, but it doesn't yet resolve the bigger question of why we are debating syntax for a referencing/validation mechanism at all.

Leveraging JSON Schema and JSON Pointer wholesale would allow the specification to focus on design‑token concepts rather than on schema‑design edge cases, and it would future‑proof the format by keeping it compatible with a broad ecosystem of tooling.

-- 
GitHub Notification of comment by brettdorrans
Please view or discuss this issue at https://github.com/design-tokens/community-group/pull/259#issuecomment-3288649028 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 17:13:59 UTC