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

@mindplay-dk these are some great questions!

The MAY/MUST part is definitely something we should correct. The correct word is MUST in both cases. And the "Recommended" part of "Current Reference Syntax" should be removed, as both are valid. I can't speak for the group in terms of what's recommended, but as the author of the updates to the syntax, I'd recommend JSON pointers.

As to the other questions:

> JSON pointers would let you write valid expressions that reference array elements - is that useful or does it create problems?

A little bit of both. It solves a problem that has been brought up a few times: sometimes, you want to use parts of a token to construct another token. here's an example:

```json
{
  "brand": {
    "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"
    },
    "light": {
      "$type": "color",
      "$value": { "colorSpace": "oklch", "components": [0.85, 0.08, "{brand.hue}"] }
    },
    "dark": {
      "$type": "color",
      "$value": { "colorSpace": "oklch", "components": [0.35, 0.15, "{brand.hue}"] }
    },
    "muted": {
      "$type": "color",
      "$value": { "colorSpace": "oklch", "components": [0.65, 0.06, "{brand.hue}"] }
    }
  }
}
```

On the downside, array references, on their own, can lack syntactic context. I see them as a sharp tool; use them in rare cases with caution.

> JSON pointers would also let you reference reserved schema elements like $type and $name - is that a "by design" feature or by accident?

You could see it both ways; it is certainly a possibility, likely born out of a hesitation to carve exceptions out of the json pointer spec. We didn't discuss it in the positive or negative ("wouldn't it be cool if" vs. "wouldn't it be bad if"). I personally don't foresee any problems if you reference a token's name or type. If you run into any, let me know!

> Does simpler syntax lack anything, or why were JSON pointers added with a "MUST" requirement?

Once we move beyond simple references — extending tokens, composing/decomposing, and importantly the syntax used in resolvers, which is essential to support multi-mode design systems — we realized that we were re-inventing the wheel. JSON pointer syntax is a well-written, well-tested, and well-supported way for JSON values to reference other JSON values. I have to admit that I was extremely skeptical at first, but over time, I was convinced that building off that schema was valuable for the long-term stability and viability of our own spec.

Put another way: to make curly brace syntax work for the future, we'd likely end up writing an equivalent of the json pointer spec, and a library's worth of code would be necessary to support it.

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


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

Received on Friday, 16 January 2026 15:41:00 UTC