JSON:API mapping guide

Endpoints extending @app/frameworks/jsonapi should keep index.js minimal and express transforms in mapping.js (+ optional helpers/compute.js).

Supported sections (overview)

Section	Role
`map`	Field-to-field mapping, nested paths, constant shaping
`pluck`	Extract subtrees from source objects
`rewrite`	Rename or restructure keys declaratively
`static`	Inject constant values into output
`group`	Array/collection handling patterns
`compute`	References to functions in `helpers/compute.js`
`parse`	Pre/post steps, sometimes `execute` hooks

Exact keys match internal jsonapi handler expectations — copy structure from a nearby endpoint in the same product area.

Design principles

Prefer declarative — if it is a straight field rename or pluck, use map/pluck/rewrite.
Isolate imperative logic — use compute for rounding, date formatting, or conditional branches that do not fit declarative rules.
One export in compute.js — utils.import warns on ambiguous modules.
Variable overrides — for {version}-style routes, you can add .../{value}/mapping.js to override base mapping.

Querystrings → backend params

Put size → limit, from → offset, filter construction in helpers/querystrings.js so jsonapi.handler builds consistent upstream requests.

See Querystrings & config.js.

Debugging

Use:

?debugga=mapping — mapping output
?debugga=compute — compute traces
?debugga=source — raw upstream payload
?debugga=request.querystrings — parsed query

Common pitfalls

Null nested paths — guard in compute or ensure pluck tolerates missing nodes.
Duplicate validation — do not re-check query params in index.js if config.js already defines them.
Large payloads — avoid logging full source in prod; use debugga only when needed.