Re: [community-group] Clarification needed for custom properties in tokens (#174)

Indeed. That's how I've been thinking about this.

To elaborate a bit further:

Conceptually, there are 2 kinds of entities in DTCG files: Groups and design tokens. The spec defines various properties that each of those can have (e.g. type, description, etc.). For edge-cases where tools or teams want to append some proprietary metadata to a token or group, they have the special extensions property.

In terms of _syntax_, both groups and tokens are expressed as JSON objects. Since both the names of a group's items (tokens or nested groups) and DTCG properties of that group are expressed as JSON keys on that object, we introduced the `$` prefix as a way of differentiating between them. All DTCG properties now and in the future willl begin with `$`, so names of items in the group are forbidden from beginning with that character (but anything else is allowed).

In order to keep the syntax of design tokens consistent, we chose to also use the `$` prefix there. Unlike groups, tokens (conceptually) can't have properties other than the ones the spec defines.

Note the JSON syntax of a design token's `$value` is strictly defined for each of the spec's available types. For some types those values are themselves JSON objects. We don't use the `$` prefix for keys within those objects.

As I understood it, the OP was asking whether JSON keys _in a design token object_ that do not have the `$` prefix are allowed or not.

While you could argue that extraneous properties on tokens do no harm, assuming that DTCG parsers will just ignore them (unless they have some special, proprietary support for them), I'd prefer for the spec to forbid them as:

* We already have `$extensions` as a place for putting any extra stuff and, [as explained above](#issuecomment-1295847906), I think it has some advantages over random, extra properties directly on the token object too.
* Admittedly this is a subjective thing, but for a human reading DTCG files, I think never having non `$`-prefixed properties on tokens might make them easier to distinguish from groups which necessarily _do_ have extra keys.



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


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

Received on Thursday, 1 December 2022 09:56:13 UTC