Discussion: Let's keep DTCG's specification lightweight and focused on interchange

[brettdorrans]

First, thank you for your efforts and the work that has gone into the technical reports so far.

I stumbled across this project while exploring the domain of design token linting, and I'm currently developing a lint-and-generate pipeline that ingests tokens from multiple design tools and outputs cross platform code. My goal was to adopt the spec as precisely as possible. In doing so, I've noticed a few areas where the current draft may be trending away from a neutral interchange format and towards defining a bespoke JSON dialect with hard-coded constraints.

I'd like to share some observations and suggestions - as an outsider, and offered with respect - to help keep the spec focused on its core, and foundational goals.

Problem areas

Narrow Unit Whitelists

Currently, dimension tokens only allow px and rem units, making a token like this formally invalid:

{
  "spacing": {
    "$value": { "value": 1, "unit": "em" },
    "$type": "dimension"
  }
}

However, em is a widely used CSS unit in production systems. Similarly, duration tokens are limited to ms and s. These narrow whitelists leave tool authors with three choices: mislabel tokens, fall back to raw strings, or fork the spec/monkeypatch in an exception. All of these go against the goal of interoperability.

I have written some more on this topic here: #245 (comment)

Some tables in the spec mirror CSS or OpenType enumerations (e.g., font weight names). These need to be manually updated whenever upstream standards change, which risks the spec falling out of sync and increases maintenance costs. We should refer to other specs, not bake these into our own spec.

Custom Referencing & Naming Restrictions

Aliases use a custom {path.to.token} syntax, which forces restrictions on characters like {, }, ., and $ in token names. This adds friction for implementers and requires special-case handling in tools and editors. This restriction exists only to accommodate existing tooling, but we should not be constrained by that when defining a new format. We can be informed by what comes before, but should not be bound by it.

I see some movement on this topic in this PR: #259

I do not think this PR goes far enough - I think we are re-inventing the wheel here and wasting time on domains that are not inside the scope of this specification. I have left some thoughts in this comment: #259 (comment)

Let's not invent a new superset of JSON when many existing tools exist, including ones we are currently in the process of re-implementing.

Suggestions

I have only just discovered this project, and no doubt many of my comments have been discussed before. However, on arrival to the repository I was disappointed to discover the spec is unfinished.

Let's be honest with ourselves: this is a solved problem. Organisations of all sizes have been doing this in production, at scale, for a long time already. This spec should be standardising approaches that already exist, not inventing new approaches. It should be done already, but has been side-tracked.

1. Treat the format as a neutral carrier: Clarify that the DTCG format is simply standard JSON, or a superset of JSON (adopted wholesale, not half re-implemented), and avoid duplicating content from existing specs e.g. CSS.
2. Wholly adopt JSON Schema and/or JSON Pointer: Do not maintain your own fork of JSON Schema. Do not spend effort arguing about syntax of solved problems. Just pick a library, and spec, and build our spec on top of it.
3. Switch to a permissive model: Allow any unit. Allow any value. As long as the JSON conforms to our schema, the contents of the object are immaterial and should be left to downstream parsers/validators to handle. Do not tie our spec to other specs in such a way we must update our spec manually. This is an interchange format, not an enforcement tool. Enforcement tools can be built on TOP of this.