Media Types and Vendor Content Types
Use this skill when selecting media type identifiers beyond plain JSON.
1. Structure (RFC 6838)
type/subtype; parameters — case-insensitive names. Trees: standards, vendor
vnd., personal prs., unregistered x. (discouraged).
Structured suffix: +json / +xml so generic parsers still work.
Example: application/vnd.api+json; version=2
2. Guidance
- Prefer standard types; mint
vnd.*sparingly when semantics truly differ. - Prefer OpenAPI/JSON Schema for structure over media-type explosion.
- Versioning: subtype version or
; version=— pick one convention. - JSON:API allows only
extandprofileparams — others → 415. - Always set Content-Type;
X-Content-Type-Options: nosniff;Vary: Acceptwhen format varies.
3. Quick checklist
- Document request/response types.
- Accurate Content-Type; nosniff.
- 406/415 behavior defined.
- Consistent MIME versioning scheme if used.
- OpenAPI lists allowed types.
See reference.md and examples.md.