Is the root node of a token tree a standard group?

[nclsndr]

I couldn't find this detail in the current spec: Do we consider the root node of a token tree a standard group? Said differently, can I have $description and/or $extensions at the root level? 👇

{
  "$description": "Tokens from brand A",
  "color": {
    "$type": "color",
    "$value": "#ff0000"
  }
}

---

It seems giving the root node the group definition opens opportunity to store global metadata. But becomes harder to work with, anytime there're more than 1 tokens file to handle.

Is there a decision about this already?

[nclsndr]

The same question goes with $type

Do we allow?

{
  "$type": "color",
  "aColor": {
    "$value": "#ff0000"
  }
}

[drwpow]

This isn’t explicit, you’re right, but the root node is a group node. Any node that isn’t a token node (contains $value) is a group node. So any properties allowed on group are allowed at the root, and will cascade as such.

There have been some proposals to add root properties (such as $name to name the file, or even a $schema to point to a JSON schema), which would change this, but none are part of the spec currently.

Out of convention, though, most people don’t place anything in the root because there’s rarely any properties that make sense to apply to all tokens ($description, $type), but there’s nothing explicitly preventing this. Both of your examples are valid.

Technically, too, the root node could be a token if it contained $value. While that’s technically valid, it’s impractical, because no one has a practical use for a design system with only one token.

[nclsndr]

Thx @drwpow for the clear answer 👍

[nclsndr]

I was looking into the spec to slide in this bit of information. But I find myself not knowing where it would fit? Anyone with opinion?