Define error handling

[romainmenke]

see : #121 (comment)

Defining which error cases can be expected while parsing a tokens file and what to do for each error is critical.

Errors carve out space for future extensions.

A simplistic example :

foo has a declared type of string but a numeric value.

{
  "foo": {
    "$type": "string"
    "$value": 10
  }
}

• this MUST be an error.
• implementations MUST NOT cast to a string ("10")
• translation tools MUST NOT generate code based on this token
• design tools MUST NOT expose this token to designers

If we allow tools to be forgiving and help authors by casting types or passing on invalid tokens we reduce the available space for future extension.

https://tr.designtokens.org/format/#typography

What if we want to add number values for lineHeight but give them specific meaning?
This is only possible if number values are not in use by accident.

edit: at the time of writing this lineHeight had a JSON value of string

---

I don't have a strong opinion about the best definition of error handling for design tokens.
But I think it is important to have some definition and then test each token type against this definition.

The main questions are :

• what if the type and value do not match?
• what if a sub value in a micro syntax is invalid/unknown?
• what if a value does not match the known options from an enum?
• what if a composite token has an unexpected shape?
• how does an invalid result affect the outcome?
• does it require a breaking change in the specification to support emerging technologies?

These questions must be seen from the perspective of a mature ecosystem.

• we have reached specification version X
• there are hundreds of tools, some only support an older version of the specification
• organizations use many different tools together