Skip to content

feat(Conformance): require an included key in answers to include - #415

Merged
thomasfosterau merged 1 commit into
trunkfrom
issue-256-included-on-include
Oct 22, 2026
Merged

thomasfosterau merged 1 commit into
trunkfrom
issue-256-included-on-include

Conversation

@thomasfosterau

@thomasfosterau thomasfosterau commented Oct 21, 2026 •

Copy link
Copy Markdown
Owner

Summary

Adds the conformance rule for 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."

  • spec/document/included-on-include (MUST, src/internal/conformance/spec.ts, after no-duplicate-resources). It reads the compound probes documentProbes already sends (?include=<inline-linkage relationships>). It also sends a bare ?include= to every read endpoint that declares include. A supplied empty include asks for nothing, so its answer has to carry included: [], which tests the empty-array case directly. That follows the fix: answer a bare ?include= and an empty related to-one with an included key (follow-up to #257) #266 decision that presence of include is the signal (comment on feat(Conformance): a rule that a response to ?include= carries an included key, even empty #256). A probe counts when its URL carries include at all, including a paths URL that already has one. Each 2xx answer must have a top-level included array. A finding names the URL and the top-level members it did find. A response to a request without include is never checked for the key. The rule reports Skipped when no endpoint declares include, or when no request carrying include drew a 2xx.
  • Fixtures (src/Conformance.test.ts). The canned baseline now answers included: [] to a supplied but empty include. A server that drops included from answers to include fails exactly this rule (broken, which also checks that nothing else fails). A server that leaves out only the empty array gets one finding per bare ?include= probe. The baseline passes over 4 probes, and its bare responses (no included) are not counted. A server that refuses every include with 400 skips the rule.
  • docs/conformance.md: rule count 61 → 62 (55 spec, 7 profile; recounted after rebasing onto trunk). §3 Document structure lists the rule and describes the extra probe.
  • Examples: blog, github and northwind all pass the rule (Passed over 8, 16 and 16 probes, checked locally), so their known-failure lists are unchanged.
  • The optional empty-relationship probe was not added. The bare ?include= probe already tests the included: [] case cheaply. Probing a relationship that resolves to nothing would mean searching the responses for empty linkage.

Closes #256
Closes #232 (its last remaining item: the builders were fixed in #257 / #266)

Verification

  • pnpm install --frozen-lockfile: passed
  • vp run build: passed
  • vp check: passed (0 errors; no new lint warnings in the changed lines)
  • vp run check (sources, type-level tests, examples, emitted declarations): passed
  • vp run -r test:unit: passed. In the full run, two test/entry-points.test.ts cases timed out at 5s while sibling worktrees were loading the machine. Rerun alone: 25/25 passed. src/Conformance.test.ts: 444/444 passed.
  • vp run docgen (every JSDoc @example compiled and executed): passed
  • fallow audit --base origin/trunk: gate verdict pass (only inherited findings remain)

Changeset

  • .changeset/conformance-included-on-include.md: minor (a new conformance rule, so a run against a server that omits the key now fails)

Notes

https://claude.ai/code/session_018ZgiUeCy5QxSz5oQt2gT1H


Generated by Claude Code

Copy link
Copy Markdown
Owner Author

The failing check is the Audit step (pnpm audit --audit-level high). Every other step is green. It is not this PR's failure: GHSA-587h-7wmj-h5pm fails trunk the same way. The fix is #416, and I'll rebase this branch onto trunk once that lands.


Generated by Claude Code

@thomasfosterau
thomasfosterau force-pushed the issue-256-included-on-include branch from 48fb7a2 to 6479594 Compare October 22, 2026 00:13
Add `spec/document/included-on-include` (JSON:API 1.1 §Fetching Includes):
every 2xx answer to a read carrying `include` must have a top-level
`included` array, `[]` when nothing is included. The rule reads the kit's
compound probes and sends a bare `?include=` to each endpoint declaring
`include`, since presence is the signal. It skips when no such request
drew a 2xx. The canned baseline answers `included: []` to a supplied
empty `include`.

Closes #256
Closes #232

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018ZgiUeCy5QxSz5oQt2gT1H
@thomasfosterau
thomasfosterau force-pushed the issue-256-included-on-include branch from 6479594 to a3de719 Compare October 22, 2026 00:57
@thomasfosterau
thomasfosterau merged commit eae2013 into trunk Oct 22, 2026
1 check passed
@thomasfosterau
thomasfosterau deleted the issue-256-included-on-include branch October 22, 2026 00:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

2 participants