You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
bug: compound documents omit included when ?include= resolves to nothing #232
JSON:API 1.1, "Fetching Includes", says that when an endpoint supports include and a client supplies it: "The server's response MUST be a compound document with an included key — even if that included key holds an empty array (because the requested relationships are empty)."
The document builders drop included when it's empty:
Handlersbuild omits included when the resolved array is empty, so included: [] and included: undefined produce the same document. The resolveIncluded docs (src/Handlers.ts, around lines 969-970) say [] and undefined mean different things, but the builders treat them the same.
Assemble.* drops an empty included too, and src/Assemble.test.ts (around lines 381-391) pins that.
PR #225 (#147) makes this reachable in one more case. GET /search?include=author, where every author is also a primary hit, now has every candidate deduped away, so the response has no included key at all. Before #225 it repeated the members instead (#147).
The conformance kit has no rule for this requirement, so CI can't see it.
Reproduction
Handlers.collection([article,author],{included: [author]})// → { data: [...] } with no `included` key, though the request carried ?include=author
Expected vs actual
Expected: when the request carried ?include=, the compound document has an included key, [] if nothing remains.
Actual: the key is omitted when nothing remains.
Suggested fix
build emits included: [] whenever the caller passed an array (options.included !== undefined), and omits it only when the caller passed undefined.
Assemble forwards [] the same way whenever the request carried include.
Update the Assemble.test.ts case that pins the omission.
Add a conformance-kit rule: a request with ?include= gets a response with an included key.
This is a published-behaviour change, so it needs a changeset.
#257 fixes the builders. It is Part of #232; the conformance-kit rule is split out to #256.
Decisions made there:
Handlers.data / Handlers.collection emit any included array, including one that is empty or that the dedupe against the primary data empties. They omit the member only for undefined.
Assemble.* decide by the request: included: [] whenever options.include is non-empty, including validate-only mode with no targets, which used to keep the key absent. That is flagged for the owner in the PR. Without include the key stays absent unless the caller's own members survive the dedupe.
The examples now pass undefined instead of [] when query.include is absent, so their responses to requests without include are unchanged.
Decision update, superseding the earlier comment's "whenever options.include is non-empty": as of PR #266 (follow-up to #257), presence of include is the signal everywhere. A bare ?include= (which decodes to []) counts as supplied and gets included: [], in Assemble.*, Handlers.resolveIncluded, ResourceHandlers.related (the empty to-one now validates include paths too) and the examples. Only an absent include omits the key.
This follows JSON:API 1.1 §Fetching Includes: "If an endpoint supports the include parameter and a client supplies it: The server's response MUST be a compound document with an included key — even if that included key holds an empty array". It also says "An empty value indicates that no related resources should be returned". The owner can reverse this by treating [] as absent; the alternative is flagged in #266.
After #266, #232's only remaining item is the conformance-kit rule, #256.
Activity
thomasfosterau commentedon Oct 8, 2026
#257 fixes the builders. It is
Part of #232; the conformance-kit rule is split out to #256.Decisions made there:
Handlers.data/Handlers.collectionemit anyincludedarray, including one that is empty or that the dedupe against the primary data empties. They omit the member only forundefined.Assemble.*decide by the request:included: []wheneveroptions.includeis non-empty, including validate-only mode with notargets, which used to keep the key absent. That is flagged for the owner in the PR. Withoutincludethe key stays absent unless the caller's own members survive the dedupe.undefinedinstead of[]whenquery.includeis absent, so their responses to requests withoutincludeare unchanged.Generated by Claude Code
thomasfosterau commentedon Oct 8, 2026
Decision update, superseding the earlier comment's "whenever
options.includeis non-empty": as of PR #266 (follow-up to #257), presence ofincludeis the signal everywhere. A bare?include=(which decodes to[]) counts as supplied and getsincluded: [], inAssemble.*,Handlers.resolveIncluded,ResourceHandlers.related(the empty to-one now validates include paths too) and the examples. Only an absentincludeomits the key.This follows JSON:API 1.1 §Fetching Includes: "If an endpoint supports the
includeparameter and a client supplies it: The server's response MUST be a compound document with anincludedkey — even if thatincludedkey holds an empty array". It also says "An empty value indicates that no related resources should be returned". The owner can reverse this by treating[]as absent; the alternative is flagged in #266.After #266, #232's only remaining item is the conformance-kit rule, #256.
Generated by Claude Code
fix: address review of the empty `included` follow-up (#232)
feat(Conformance): require an `included` key in answers to `include`
feat(Conformance): require an `included` key in answers to `include`