Content-Type Headers for Data APIs: JSON, YAML, TOON, and Plain Text

Content-Type is the header agents trust first. It tells a parser what grammar to use before a single byte is read. Get it wrong and a valid payload becomes an invalid one.

What YJTOON serves

• application/json; charset=utf-8 for JSON (dynamic API and static .json files)
• text/yaml; charset=utf-8 for YAML (dynamic API and static .yaml files)
• text/plain; charset=utf-8 for TOON from the API — TOON is its own grammar, so plain text is the honest label

Why plain text for a custom format

A custom format should never borrow someone else's content type. If TOON claimed text/yaml, a YAML parser would try to parse it and produce confusing failures. text/plain tells the consumer: this is a text format, parse it with its own grammar.

The charset part matters

Reference data is full of non-ASCII characters — accented names, em dashes, math symbols. ; charset=utf-8 prevents mojibake when a consumer assumes Latin-1.

What agents should do

Check Content-Type before parsing, especially when a service changes formats. A JSON parser fed YAML is a common failure mode that a one-line header check prevents.