YAML as an alternate format

[drwpow]

The current design tokens spec is in JSON, and that’s great! Forgive me if this has been talked about already, but I’d like to propose YAML as an alternate format for design tokens specification.

One precedent for this is the OpenAPI specification, arguably the most popular way to document APIs. It is great prior art on a time-tested specification format, and one of the things that’s led to its adoption (I think) is the ability to use either schema.json or schema.yaml formats. Adopters of OpenAPI can choose JSON or YAML—whichever they prefer—because perhaps one fits better with their tooling and in the end both produce identical results.

There has already been a comparison of JSON vs YAML discussed in #1. But that was asking JSON OR YAML, and I’d like to ask if JSON AND YAML makes sense (with JSON remaining the default/preferred format as already decided). Borrowing some points from that comment, and expanding on it, here would be some of the advantages:

• Code generation with YAML is just as easy as JSON (in some circles YAML is preferred)
• YAML tooling is just as ubiquitous and readily-available as JSON tooling (often many libraries handle both)
• YAML is friendlier to read and write with fewer extraneous characters
• YAML allows comments (JSON doesn’t)
• (opinion) More teams will adopt the design tokens spec if they can choose whichever format better fits their current tooling

Lastly, to the point about “JSON being better for APIs,” I would disagree, also citing OpenAPI returning YAML as a good example. Whitespace weight becomes negligible when gzipped which any good API response will do. Further, few—if any—systems should rely on design tokens at runtime (building your tokens into code ahead-of-time will always be more reliable and more performant), so API response time shouldn’t be a deciding factor in format; the user writing experience should (and in my opinion, writing YAML is very user-friendly).

Again, forgive me if there was a discussion I missed, but I wanted to get peoples’ thoughts on this question I’ve had. Thanks so much to the people organizing this project together, and I’m already excited by the current direction and amount of thought that’s been put into it!

[c1rrus]

No need to apologise! We're keen for folks to question and challenge things in the spec draft.

We considered things like YAML and also extensions to JSON like JSON5 but eventually settled on plain JSON as we felt that was the most widely and consistently supported across different programming languages.

As for supporting YAML and JSON, my main concern would be interoperability. The goal of our spec is define a file format that allows people to easily and reliably exchange design token data between various tools. Any tool that supports the spec should be able to read or write files that any other tool that also supports the spec can handle. Therefore, if we allow both YAML and JSON that would mean that every tool that supports our spec would need to be able to read both formats.

My gut feel is that the extra work and testing that each tool vendor would have is likely to be a bigger barrier to adoption than JSON (arguably) being a bit less friendly to write than YAML.

[drwpow]

Therefore, if we allow both YAML and JSON that would mean that every tool that supports our spec would need to be able to read both formats.

I can respect that. And I can also see how focusing on a single, unified format for now is the best way forward. As for OpenAPI supporting both, I’m actually not sure when it happened, but it is interesting that it has developed alongside JSON Schema and for the most part does tend to be JSON-focused.

I can respect not adding distractions now to the current priority of figuring out the general schema and token types, so again, JSON seems like a solid choice! Perhaps in the far future YAML could be considered if, as you said, the tooling has already stabilized and the community at large agrees.