Response specifications
Routes set specification to a key defined under src/settings/specs/. That controls response headers and serialization expectations (e.g. JSON:API content-type).
framework vs specification
| Concept | Role |
|---|---|
framework |
Execution path when no endpoint index.js exists — e.g. template, staticish. |
specification |
HTTP layer — content-type, JSON:API profile, mobile headers, etc. |
In practice most endpoints have an index.js, so framework on the route may be ignored (Router warns). specification still applies.
Common spec keys
| Spec | Typical use |
|---|---|
json |
Plain JSON; may support JSONP patterns where configured |
json-api |
application/vnd.api+json JSON:API responses |
mobile |
Mobile app JSON contracts |
xml |
RSS, sitemaps, partner XML |
html |
HTML fragments or pages |
text |
Plain text |
swagger |
OpenAPI/Swagger YAML with CORS for docs UIs |
Exact header sets live in src/settings/specs/ — always verify there before relying on client behavior.
Choosing a spec
- Spark-style JSON:API handlers —
json-api+@app/frameworks/jsonapiinindex.js. - Mobile tab / spark tab — often
mobile. - Feeds —
xmlwith template framework (when no customindex.js) or custom handler returning XML bodies.
Client impact
- Android / iOS may assume specific content-types for caching and parsers — changing a spec is a contract change.
- Partners (RSS) may validate XML declarations and namespaces — test with real fetches, not only local curl.