Re: [community-group] Add a "$specificationURL" or "$specificationUrl" or "$specification" (required) property to the "$extensions" property for vendors (#144)

That's an interesting idea.

In my opinion, `$extensions` should be treated as a last resort when a DS team or tool really needs to add some extra metadata to a token ([or, potentially, group](https://github.com/design-tokens/community-group/issues/106)) and there really is no other way of doing it via any of the standard properties provided by the spec.

Overuse and misuse of it would certainly be dangerous as it could hurt interoperability between tools. However, it's very likely that the spec won't cover every edge-case and having an official "escape hatch" is better than having teams either not use the format at all or produce invalid files by adding custom properties elsewhere (which might also be potential naming clashes with official properties introduced in future spec versions).

I like your idea as it could help increase visibiltiy of extensions folks are defining which would be really useful to the DTCG. If we see many teams and/or tools creating extensions to solve similar problems, that's would be an excellent candidate for something to be formalised in a future version of the spec. It would enable us to "pave the cow paths". (I had recently been wondering whether [our website](https://www.designtokens.org/) could one day also have a section where we list known extensions, which could be a complementary way of improving visibility of what extensions are out there).

I'm not sure it would be wise to make it mandatory though. Doing so would raise the barrier to entry for anyone defining an extension as they'd need to have a spec for it available at the end of a URL. While I think that publishing specs for extensions is something we should strongly _encourage_, I can see cases where it might be an unreasonable burden. For example, a design system team that uses extensions in some internal, home-grown tool that they never intend to make public. Or individuals and teams that are still experimenting and prototyping something that requires extensions.

Another question is where, exactly, that property should go. Currently, the value of an extension can be anything you like. We therefore can't assume it's always an object that a `$specificationUrl` property could be added to. Also adding specification URLs to the extensions themselves or the enclosing tokens could become very repetitive if the same extension is used by many tokens in the same file.

Therefore, how about this: At the top level of the file (i.e. the root group) you can add an _optional_ `$extensionSpecifications` property, whose value is an object that maps extension names to the corresponding specificiation URLs. That way the extension spec URLs can only be declared once in a specific place.

For example:

```jsonc
{
  "$extensionSpecifications": {
    "com.example.foo": "https://example.com/design-tokens/extension-specs/foo/",
    "org.other.bar": "https://design-system.other.org/specs/bar"
  },

  "token-1": {
    "$type": "color",
    "$value": "#ff0000",
    "$extensions": {
      "com.example.foo": 99,
      "org.other.bar": {
        "baz": false,
        "quux": 42
      }
    }
  },

  "token-2": {
    "$type": "dimension",
    "$value": "0.75rem",
    "$extensions": {
      "com.example.foo": 75,

      // It's optional for extensions to declare spec URLs,
      // so there could also be ones that don't:
      "com.example.bar": "Hello World"
    }
  },
}
```

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


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

Received on Sunday, 26 June 2022 22:33:54 UTC