JSON:API

JSON:API v1.1 (jsonapi.org/format/1.1/) response-shape helpers. The framework's wire-format primitives compose this so operators building JSON:API services get the right top-level shape + the right Content-Type without re-implementing the spec each time.

Content-Type: application/vnd.api+json

Top-level shapes: - dataResponse(data, opts?) — { data: [...] | {...}, included?, links?, meta? } - errorResponse(errors) — { errors: [...] } - linkObject(url, opts?) — string href OR { href, rel, meta }

b.jsonApi.dataResponse(data, opts?) #

{
  included: ResourceObject[],   // compound documents §7.7
  links:    object,             // top-level links §7.5
  meta:     object,             // non-standard top-level meta §7.4
  jsonapi:  object,             // jsonapi-object §7.3 (version etc.)
}

Build a JSON:API v1.1 success response. data can be a Resource Object, an array of Resource Objects, or null (for single-resource 404 / empty-collection responses). Each Resource Object must carry type + id (§7.2).

res.setHeader("Content-Type", "application/vnd.api+json");
res.end(JSON.stringify(b.jsonApi.dataResponse(
  { type: "articles", id: "1", attributes: { title: "Hello" } },
  { links: { self: "/articles/1" } }
)));

b.jsonApi.errorResponse(errors, opts?) #

{
  meta:     object,    // optional top-level `meta` block (JSON:API §5.3)
  jsonapi:  object,    // optional top-level `jsonapi` member (JSON:API §5.2 — version / ext / profile)
  links:    object,    // optional top-level `links` (JSON:API §5.4 — self / related / pagination)
}

Build a JSON:API v1.1 error response per §7.6. Each error object can carry id / status / code / title / detail / source / links / meta. The framework refuses errors lacking BOTH status and title (most JSON:API consumers need at least one).

res.statusCode = 422;
res.end(JSON.stringify(b.jsonApi.errorResponse([
  { status: "422", code: "INVALID", title: "Invalid email",
    source: { pointer: "/data/attributes/email" } },
])));

b.jsonApi.parseQuery(queryString, opts?) #

{
  includeAllowlist:    string[],
  sortAllowlist:       string[],
  maxIncludeDepth:     number,    // default 5
}

Parse a JSON:API v1.1 query string per §5 (Fetching Data). Returns { include, fields, filter, sort, page }: - include — array of relationship paths from include= (comma-split) - fields[type] — array of sparse-fieldset selectors per type - filter — pass-through object (spec defers filter shape to operators) - sort — array of { field, asc } per RFC 7159-style direction - page — pass-through object (operator picks page-strategy)

Refuses missing required include paths when opts.includeAllowlist is supplied and an unrecognized path appears.

var q = b.jsonApi.parseQuery(req.url.split("?")[1]);
q.include;         // → ["author", "comments.author"]
q.fields.articles; // → ["title", "body"]
q.sort;            // → [{ field: "createdAt", asc: false }]

Last updated 2026-08-08T16:39:49.652Z by seeder.