Skip to content

bug: compound documents omit included when ?include= resolves to nothing #232

Closed

Description

@thomasfosterau

What's wrong

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:

  • Handlers build 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.

Context

Found by the review of PR #225 (#147).


Generated by Claude Code

Activity

  1. thomasfosterau commented on Oct 8, 2026

    @thomasfosterau
    OwnerAuthor

    #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.

    Generated by Claude Code

  2. thomasfosterau commented on Oct 8, 2026

    @thomasfosterau
    OwnerAuthor

    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.


    Generated by Claude Code

  3. added 2 commits that reference this issue on Oct 22, 2026
    6479594
    a3de719
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions