TOON support in OpenAPI 3.3?

[miqui]

This proposal recommends adding support for TOON as a structured data format in the OpenAPI Specification, for example via a registered media type such as application/toon. The aim is not to replace JSON as the default wire format, but to provide an alternative representation for operations where the primary consumer is an LLM or AI agent and token-efficiency is a key requirement. TOON’s design—schema-aware, tabular-friendly, and punctuation-light—allows the same OpenAPI-described schema to be serialized with significantly fewer tokens than JSON, improving cost, latency, and context utilization in AI-heavy systems.

[miqui]

@lornajane , @ralfhandl , @handrews - what do you think my friends?

[miqui]

https://openapi.com/blog/what-the-toon-format-is-token-oriented-object-notation

[ralfhandl]

Primary source: https://github.com/toon-format/spec

[ralfhandl]

I recommend skipping the blog and directly go the primary source, the blog doesn't even link to the TOON spec 🙄

[handrews]

@ralfhandl thanks! @miqui it looks to me like all this needs is an entry in the Media Type Registry that says that since it (to quote the spec) "encodes the JSON data model" you can use a Schema Object in the same way that you would use it for JSON (or JSON-compatilble YAML, or TOML, not that I put those in the registry because people rarely use them in APIs).

The "schema-aware" parts seem to just be part of each individual document's serialization, so TOON encoders/decoders will handle that without the OAS needing to be involved.

I think the only 3.3 question here is whether we should mention TOON specifically in 3.3, and given the AI/LLM angle, I would be in favor of doing so (briefly, possibly while noting other LLM-friendly features). But I think if we put it in the registry people would be free to use it with 3.2 (or even earlier, since it is just an alternate encoding of JSON and requires no special support).

[handrews]

Although I guess there's also a question of if we want to require (MUST), recommend (SHOULD) or just allow (MAY, or just leave it in the registry) support for TOON in tools. A MUST would offer the most interoperability, but idk if TOON is sufficiently widely used/supported for that. I would be more likely to support a SHOULD or MAY while we wait and see if TOON has real staying power.