Skip to content

feat(Conformance): derive declared cardinality for links-only relationships - #418

Merged
thomasfosterau merged 1 commit into
trunkfrom
issue-390-links-only-cardinality
Oct 22, 2026
Merged

thomasfosterau merged 1 commit into
trunkfrom
issue-390-links-only-cardinality

Conversation

@thomasfosterau

Copy link
Copy Markdown
Owner

Summary

Closes #390.

spec/links/relationship-self-dereferences now checks a links-only relationship's self link against the cardinality the api declares for it. Until now it took either cardinality.

  • Discovery (src/internal/conformance/core.ts): Discovered.linkage (new type Cardinality, moved from links.ts) holds, for each relationship-role endpoint, what its success schema's encoded data declares:
    • "one": an identifier object or null.
    • "many": an array.
    • "unshown": a schema it cannot read (Schema.Unknown, no data, a union whose members disagree), and every other role.
  • The rule (src/internal/conformance/links.ts): when the relationship object has no data, relationshipSelfLinks resolves the self link and drops the base URL from its path. If that path fills a declared relationship endpoint's path (each literal matching exactly, :param matching any segment), the claim takes that endpoint's cardinality. It falls back to "unshown" (either kind passes) when:
    • no endpoint matches (another origin, an undeclared path)
    • the schema says nothing
    • the endpoints that match disagree
  • The finding names its source. Its detail adds ", as the relationship endpoint articles.commentsRelationship (GET /articles/:id/relationships/comments) declares", and expected says the endpoint's success schema declares the cardinality. Findings based on linkage the relationship shows read word for word as before.
  • The SHOULD (relationship-self-matches-linkage) is unchanged.
  • docs/conformance.md: the §3 rule table row, the fallback sentence, the examples paragraph and the test inventory are updated.

Verification

Run in order in the worktree, after rebasing onto origin/trunk (which includes the vite-plus 1.3 / tsgo 0.55 bump):

  • pnpm install --frozen-lockfile: pass
  • vp run build: pass
  • vp check: pass (0 errors; the warning count is the same as trunk's, 4325)
  • vp run check: pass ("every type gate green")
  • vp run -r test:unit: pass. In the full run on a loaded machine, 2–3 test/entry-points.test.ts cases timed out (they walk dist/). Run alone, that file passes 25/25, and the blog, github and northwind example suites pass when run separately.
  • vp run docgen: pass
  • fallow audit --base origin/trunk: pass ("No issues in 6 changed files")

Changeset

  • .changeset/links-only-cardinality.md, minor: the rule now fails servers it used to pass (a paginated to-many relationship whose relationship endpoint answers one identifier).

Notes

  • Tests:
    • src/Conformance.test.ts, one new case:
      • Declared, conforming answers: a links-only paginated comments (to-many) answering an array and a links-only author (to-one) answering one identifier pass.
      • Declared, wrong answers: each relationship answering the other cardinality fails, with detail and expected pinned.
      • No matching endpoint: with only author declared, comments takes either kind.
      • Unreadable schema: hand-built Schema.Unknown relationship endpoints take either kind.
    • src/internal/conformance/core.test.ts: a new describe at the end of the file pins the cardinality discovery reads for one, optional, many and paginated, and for a Schema.Unknown or data-less success.
  • The existing "links-only takes either" assertion still holds, because the main fixture api declares no relationship endpoint.
  • Declared cardinality is used only when the relationship carries no data. Linkage the relationship shows still wins, as the issue specifies.
  • A relationship endpoint mounted at a custom path that roleOf does not classify as relationship (anything other than GET /<type>/:id/relationships/<name>) is not consulted.
  • To stay clear of fix(Conformance): read a headers union whose every member requires Idempotency-Key as required #405, the diff in core.ts leaves idempotencyKeyOf and the idempotencyKey field alone.

Generated by Claude Code

…nships (#390)

Discovery records the cardinality each relationship endpoint's success
schema declares; relationship-self-dereferences holds a links-only
relationship's `self` link to the cardinality of the declared
relationship endpoint it resolves to, naming that endpoint in the finding.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018ZgiUeCy5QxSz5oQt2gT1H
@thomasfosterau
thomasfosterau merged commit 434239f into trunk Oct 22, 2026
1 check passed
@thomasfosterau
thomasfosterau deleted the issue-390-links-only-cardinality branch October 22, 2026 00:06
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.

feat(Conformance): derive declared cardinality for links-only relationships (from the relationship endpoint's success schema)

2 participants