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

**tl;dr:** i don't think we should replace the current alias syntax with the `$ref` syntax:
1.  i like the benefits of introducing pointer syntax to allow for more precise aliases and overrides, but i think these can be accomplished in a syntactically compatible way with the current (object notation) format. 
2. making the jump to multi-file data is complicated and i think we should consider it separately from syntax/format

---

Long version / stream of consciousness:

There's one few minor question marks and one major question mark in my head:

1. Minor: going away from {foo.bar.baz} does lose the nice hint that tokens are meant to be nested as javascript objects. `#/color/blue/500/$value` feels less javascript-object-y than color.blue.500.$value, and carries the connotation (to me at least) that these are folder structures instead. However, in my adventures writing tools, I tend to just 'flatten' the dtcg JSON to make it easier to access tokens, so i don't see one being performance-wise better than the other.

2. Minor: As far as I can tell `$ref` was originally designed for JSON schema, not JSON data itself. While that alone isn't disqualifying, it does make me suspicious that it might not be the right tool for the job; there are a lot of consequences to adopting it wholesale that we will have to pick through.

3. Very minor: in my opinion escaping `/` and `#` with `~0` and `~1` is pretty esoteric, and makes my eyeballs itch a little.

4. Major: a token file might be syntactically valid (ie contain refs formatted correctly), but aliases may not be possible to resolve — if the file you're referencing has moved, or if it's on a server that can't be accessed. I really like the implied feature of the current format, which is that a file with nesting and aliases can be statically analyzed for circular references, and if none exist, it can be safely[^1] converted into a flat dictionary with no aliases. I feel like making the jump to multi-file should be separated out from the other ideas, which can be brought through under single file constraints.

For example, I agree that being able to grab more than just the `$value` of an aliased token is valuable. There a way to refine the current object notation in a way that allows for things like:

```json
{
  "color":{
    "blue":{
      "$type":"color",
      "$description":"The color blue",
      "$value":{
        
      }
    },
    "brand":{
      "$type":"color",
      "$description":"our brand color",
      "$value":"{color.blue.$value}"
    }
  }
}
```
Overrides are tricky, but I do think that we could add that to the current spec without breaking backwards (syntactic) compatibility. 

```json
{
  "color.brand": {
    "$value": "{color.blue}",
    "$description": "our brand color"
  }
}
```
To a few of your points:

> When a schema isn’t distinguishable by structure, tool makers have to do additional work string matching to do basic typecasting and discrimination.

and

> Out of all the approaches, https://github.com/design-tokens/community-group/pull/3 would be beneficial being the easiest to statically-analyze. You could tell which tokens are aliases without having to resolving any pointers.

I agree that trying to differentiate an alias from a non-alias string feels somehow philosophically _wrong_, but I haven't had trouble detecting aliases with the current spec. I'm certainly not the most experienced implementer, so my attempt might be naive, but in my resolver I have this function:

```ts
function isTokenAlias(tokenValue: TokenValue): boolean {
  return typeof tokenValue === "string" && tokenValue.startsWith("{") && tokenValue.endsWith("}");
}
```

Or you could use the regex `/^\{.*\}$/` if you like that kind of thing.

Identifying an alias by looking at the key and asking if it is === `$ref` seems philosophically more correct, in in practice takes the same number of steps and is still, ultimately, string matching.

Either way, I'm for the spirit of proposal #1, in terms of allowing someone to alias an entire object or to cherry-pick attributes.

> 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 take this to mean that in JSON schema world, referencing another schema or part of a schema is both semantically and functionally different than "flattening" the reference into a single static document. For example, if our schema for dtcg files references a specific json schema, we're saying "if that json schema is updated at some point, the updates apply to our schema, too." This is different than simply copy-pasting the schema into ours, which loses the dynamic relationship between the two.

I believe the current alias format (object notation) respects both the semantic and functional differences between "foo is an alias for bar which has the value of baz" and "foo has the value of baz". 

In a single file world, there is no functional difference at all, but the semantic difference is important and remains.

The only place where I think `$ref` becomes valuable is in a multi-file world. 

[^1]: By "safely", I mean the semantics are preserved, eg a chain of nested references like color.brand.primary → color.blue.500 → #0000ff chain will deterministically be resolved to "color.brand.primary" = "#0000ff". 

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


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

Received on Friday, 28 March 2025 01:51:15 UTC