Re: [community-group] Conflicting language in "References and JSON Pointer Integration" (#383)

```
    "primary": {
      "$type": "color",
      "$value": { "colorSpace": "oklch", "components": [0.65, 0.18, 264] }
    },
    "hue": {
      "$type": "number",
      "$ref": "#/brand/primary/$value/components/2",
      "$description": "Shared hue for brand color family"
    },
```

Frankly, this looks... pretty bad. 😐

With JSON pointers, you get references that are tightly coupled to protocol details - in this example, you are counting on `brand/primary` to be defined using a specific `{ "colorSpace": "oklch", "components": [0.65, 0.18, 264] }` structure, but there are obviously many ways to define a color; changing a simple color declaration is now a breaking change.

That reference would have been much more reliable as e.g. `{brand.primary.lightness}` - a *computed* property that could be calculated for any color regardless of how you happened to define that color.

Defining which computed properties are available for colors and other types of course would require some foot work, on the specification side, and for implementers - but it also gives you *stable* references that don't randomly break when you change what should be an implementation detail. Libraries such as [color](https://www.npmjs.com/package/color) worked hard to make sure that different constructors all return a `Color` instance, from which you can *always* obtain the lightness component, or any other component, regardless of how the color was defined.

The example per se looks... odd?

If you were declaring a  "Shared hue for brand color family", ideally, you'd probably want this to be declared as your primary "source of truth" value, from which you derive concrete colors - and *not* a value derived from a reference.

Either way, what can you do with a component value? Is this valid?

```
    "primary": {
      "$type": "color",
      "$value": { "colorSpace": "oklch", "components": [0.65, 0.18, { "$ref": "#/brand/hue/$value" }] }
    },
    "hue": {
      "$type": "number",
      "$value": 264,
      "$description": "Shared hue for brand color family"
    },
```

Is this?

```
    "primary": {
      "$type": "color",
      "$value": { "colorSpace": "oklch", "components": [0.65, 0.18, { "$ref": "#/brand/hue" }] }
    },
```

Would the referenced `{ $type: "number", ... }` object resolve to a value?

This just seems to get really confusing and fragile - it likely creates a lot of apparently valid references for which the spec doesn't include any defined behavior?

This would seem a lot simpler for authors:

```
    "primary": {
      "$type": "color",
      "$value": { "colorSpace": "oklch", "components": ["{brand/hue}", 0.18, 264] }
    },
```

It's not clear to me if that's intended to work either though.

But at least in your example this would decouple you from the color declaration:

```
    "primary": {
      "$type": "color",
      "$value": { "colorSpace": "oklch", "components": [0.65, 0.18, 264] }
    },
    "hue": {
      "$type": "number",
      "$value": "{brand.primary.hue}",
      "$description": "Shared hue for brand color family"
    },
```

I don't know, JSON pointers seems to give you way too many options - it seems deceptively open-ended to me, a quick way to avoid specifying something more robust that doesn't couple you to protocol details.

Even if you don't specify computed component properties for every type, if it's just the basic "whole token" reference that is currently supported by the simpler `{name.value}` syntax - if this doesn't give you the same level of flexibility as JSON pointers, the basic reference syntax still seems like an overall more robust and predictable mechanism to me.

Do we even *need* that level of flexibility in token files? Do you foresee people hand-writing these files? It seems to me like this format will play more of a role as an intermediary format between design tools and code (generation) tools?

Once the tokens are out of your design (system) tool and being handed off to parse or convert to CSS etc. does it matter if those color calculations are done dynamically or ahead of time in your design tool?

Either way, I'm concerned JSON pointers might raise more questions than answers. 😌


-- 
GitHub Notification of comment by mindplay-dk
Please view or discuss this issue at https://github.com/design-tokens/community-group/issues/383#issuecomment-3765047319 using your GitHub account


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

Received on Sunday, 18 January 2026 08:20:01 UTC