Skip to content

feat(Conformance): split the self link rules into MUST and SHOULD (#309) - #384

Merged
thomasfosterau merged 1 commit into
trunkfrom
issue-309-self-link-split
Oct 15, 2026
Merged

thomasfosterau merged 1 commit into
trunkfrom
issue-309-self-link-split

Conversation

@thomasfosterau

Copy link
Copy Markdown
Owner

Summary

Refs #309. This is a follow-up to #376. It applies the owner decisions on #309 (issuecomment-6190325231, 2026-10-15) and the #376 review nits.

Both self link rules now split into a MUST and a SHOULD, following the #312 precedent (related-dereferences / related-matches-linkage). Each SHOULD leaves a link that its MUST fails as not decided, and names the MUST: a link that does not parse, answers a non-2xx, or answers something the MUST rejects. So a single broken link is never failed twice.

Rule Level Holds the answer to
spec/links/relationship-self-dereferences MUST (§Fetching Relationships) A 2xx with resource linkage of the right shape: null, a resource identifier object, or an array of them. Identifier objects only: a string type, a string id or lid, and nothing else but meta. Full resource objects (attributes / relationships / links) fail; previously isResourceObject only checked for a string type. The cardinality must also match the relationship's linkage: null or one identifier for to-one, an array for to-many.
spec/links/relationship-self-matches-linkage (new) SHOULD (§Relationships, no keyword) The same identifiers as the relationship object's linkage. Equality, a subset when either side carries next, and not decided when both do.
spec/links/top-level-self-dereferences MUST (§Fetching Resources) A 2xx with resource data.
spec/links/top-level-self-matches-document (new) SHOULD (§Document Top Level, no keyword) A document of the same kind: the same resource, null for null, or a collection for a collection. The collection comparison is unchanged: an unordered set, compared only when neither document pages.

skip: ["spec/links/"] drops all seven link rules, and a test pins this. The example relationship endpoints stay.

Review nits

  • links.ts (non-2xx expected): "the related resource data" is restored and pinned by a test. ANSWERS gains a named field so that the wording for each basis is explicit.
  • The skip reason for the top-level rules (noProbeReason) now names "JSON:API read endpoint answering a document" instead of "endpoint answering resource objects". A test pins it.
  • The example conformance tests (blog, github, northwind) pin all four self rules: both MUSTs Passed, top-level-self-matches-document Passed, and relationship-self-matches-linkage Skipped, because the only relationships with a self link are the links-only paginated ones.
  • examples/github/api.ts module doc: mentions relationships/comments.

Docs and changeset

  • docs/conformance.md: rule count is 57 (51 spec, 6 profile) with six gaps. The old status line said 52 and seven, which was already stale before this PR.
  • §1.5: "seven link rules".
  • §3: table, levels paragraph, and per-link bullets.
  • §8: example outcomes.
  • §9: test inventory.
  • §10: the top-level self question is marked answered.
  • §5 needed no change: feat(Conformance): follow relationship and top-level self links #376 already removed the gap row, and nothing else in §5 concerns these links.
  • The README lists no individual link rules; only the skip example, which is still correct.
  • .changeset/conformance-self-link-rules.md is not in tag @thomasfosterau/effect-jsonapi@0.16.3, so it is unreleased. It is edited in place and stays minor.

Tests and mutation checks. Each mutation was applied to links.ts and the link suite was run. Every one was killed:

Mutation Tests failed
Accept extra members on an identifier (full resource objects pass) 1: the full-resource-objects test
Drop the cardinality check 1: the wrong-cardinality test
Relationship SHOULD stops deferring to its MUST 3
Top-level MUST uses the SHOULD's document claim 3
Relationship SHOULD stops comparing to-one identity 2
Top-level SHOULD stops deferring 2
Old skip-reason wording 1
"related resource data" without "the" 1
MUST takes the SHOULD's linkage claim 6
Deferral note says "its linkage" for the top-level rule 2

The github example's pin was checked the same way: a paginatedRelationship self pointed at /issues/:id/relationships/nowhere fails both the pin and KNOWN_FAILURES.

Verification

  • pnpm install --frozen-lockfile: pass
  • vp run build: pass
  • vp check: pass (0 errors; 4351 warnings, the same as trunk; no new warning sites in the changed files)
  • vp run check (sources, type-level tests, examples, emitted declarations): pass
  • vp run -r test:unit: pass (root 3519 tests, examples 44 / 46 / 56)
  • vp run docgen (every JSDoc @example compiled and executed): pass
  • fallow audit --format json --quiet --explain --gate-marker agent: verdict pass
  • fallow audit --base origin/trunk: "No issues in 9 changed files". 7 inherited findings are excluded.

Changeset

  • A changeset under .changeset/ for every change to published behaviour: .changeset/conformance-self-link-rules.md (minor) is rewritten in place. It is unreleased: it is not in @thomasfosterau/effect-jsonapi@0.16.3.

Notes

  • Where cardinality comes from (proposed default, flagged for the owner). The kit reads "to-one or to-many" from what the relationship object's own linkage shows: null or an object means to-one, an array means to-many. A links-only relationship, such as every Handlers.paginatedRelationship, shows no cardinality, so it is held only to answering linkage of either kind. The kit does not read the declared Relationship from the HttpApi: Discovered carries no relationship schema. Deriving it from the api would also hold links-only relationships to their declared cardinality. That is possible later, if wanted.
  • An identifier named only by lid passes the MUST. The SHOULD compares by type/id, so it cannot compare that identifier and leaves the link not decided, as it does for any answer it cannot identify.
  • Handlers.paginatedRelationship always writes a relationship self link, even when no such endpoint is declared #381 (Handlers.paginatedRelationship always writes a relationship self link) is untouched.

🤖 Generated with Claude Code


Generated by Claude Code

…309)

Follow-up to #376, per the owner decisions on #309 (2026-10-15).

- `spec/links/relationship-self-dereferences` (MUST) now holds a
  relationship's `self` to answering resource linkage of the right shape:
  `null`, a resource identifier object or an array of them, identifier
  objects only (`type`, `id`/`lid`, `meta`), so full resource objects fail,
  with the cardinality the relationship's linkage shows.
- New `spec/links/relationship-self-matches-linkage` (SHOULD) compares the
  answer's identifiers with the relationship's linkage: equality, a subset
  when either side carries `next`, not decided when both do.
- `spec/links/top-level-self-dereferences` (MUST) holds a top-level `self`
  to answering resource data.
- New `spec/links/top-level-self-matches-document` (SHOULD) holds it to a
  document of the same kind, the collection comparison unchanged.
- Each SHOULD leaves what its MUST fails not decided, naming it, as
  `related-matches-linkage` does since #312.
- Review nits: restore "the related resource data" in the non-2xx
  `expected`; name the endpoints the top-level rules search in their skip
  reason; pin the four outcomes in each example's conformance test; mention
  `relationships/comments` in the github example's module doc.

Docs (`docs/conformance.md` §1.5, §3, §8, §9, §10) and the unreleased
changeset updated.

Refs #309

Claude-Session: https://claude.ai/code/session_0187g2QpzaHqEzX8GJxiJBVc
Co-Authored-By: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants