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

@c1rrus great thoughts, thank you! 🙏 I wanted to think on the points you raised for a few days.

> In many cases, the intent is to merge all the source files into a single collection of tokens, and then to do stuff with it. This is how tools like Theo and Style Dictionary have been doing it forever and I'd argue the Resolver Spec is another (more advanced) take on that concept too. Resolving design token references doesn't happen until after that file merging process has been done, so there's no need for them to specify a file that a token is in.

This is a great callout, and I think really gets at the mental model of how people think about the DTCG spec now, how people _want_ to think about it, etc. So this is exactly the conversation I wanted to have with this proposal, even if it doesn’t move forward.

Specifically “Resolving design token references doesn't happen until after that file merging process has been done” doesn’t have to be how this works! Again, see the comment from the JSON spec:

> Attempting to remove all references and produce a single schema document does not, in all cases, produce a schema with identical behavior to the original form.

I interpret this as working exactly as aliases work today—you don’t have to preresolve those preemptively, and you can (and should) preserve all the pointers as actual pointers (not deep clones of the data). I do realize the spec changes as-written are confusing about that, so I should update the examples. But this can work the exact same as aliases do. And leaning on how JSON pointers are used today, the filenames themselves are negligible, again, they can work the same. It just removes the restriction of keeping tokens in files _by necessity_ and moves it to a pattern where you can put any token in any file _by choice_. You can point to tokens in the same file, or remote files. Up to you.

> Yes, the current syntax requires a little bit of string parsing to detect a reference versus an actual value, but I'm not convinced that if ( `token.$value.charAt(0) === '{'` ) is any more difficult than if ( `typeof token.$value === 'object' && token.$value.$ref !== undefined` ).

Yeah performance wasn’t a primary motivator of the change, but this is mostly only true in JavaScript. I agree with you—it is fairly-trivial to parse and typecast on-the-fly. But in other languages that rely more heavily on fixed structures and memory allocation, leaning on typecasting that’s apparent at the schema level (like [serde](https://serde.rs/) for Rust) is much simpler. Again, not to mention the fact that for JSON `$ref`s, every language already has existing tooling to understand, parse, and resolve these.

---

As an aside, after writing this I did think about the relation between this and the Resolver Spec more, and I reached the conclusion the Resolver Spec in its current form is sufficient, and whether we accept or reject this proposal won’t change that. The problems I also _thought_ I would hit in the Resolver Spec ended up not being problems at all when I worked through a [complex example](https://gist.github.com/drwpow/6e9902f2815f27f7ae8f87370bff5b33)!

So all that to say I’d like to evaluate this solely on the basis of:

1. Does this solve problems for the current state of DTCG, and DTCG alone? (I think so)
2. Does this “stand on the shoulders of giants” and use familiar, prior art? (I think so)

And we may come to the conclusion “no” and that’s OK with me. I’m happy whether this is accepted or rejected; so long as we evaluated it.

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


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

Received on Monday, 13 January 2025 20:03:24 UTC