Skip to content

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

Closed

Description

@thomasfosterau

Problem

spec/links/relationship-self-dereferences (the MUST rule, #309, merged in #384) holds the answer to a relationship's own self link to linkage of the relationship's cardinality: null or one identifier for to-one, an array for to-many. It reads that cardinality off the relationship object's own linkage (data). A links-only relationship carries no data (every Relationship.paginated, through Handlers.paginatedRelationship), so the rule falls back to accepting linkage of either kind (cardinalityOf returns "unshown" in src/internal/conformance/links.ts).

The fallback is described in docs/conformance.md §3. It means a paginated to-many relationship whose relationship endpoint answers a single identifier passes the MUST, though §Fetching Relationships requires "the appropriate value for resource linkage", which for a to-many relationship is an array.

The api often says what the cardinality is. When the relationship's self link resolves to an endpoint the api declares (Endpoint.getRelationship, role relationship in discovery), that endpoint's success schema is a LinkageDocument whose data is either an identifier (or null) or an array of identifiers.

Proposal

  • During discovery (src/internal/conformance/core.ts), record for each relationship-role endpoint the cardinality its success schema declares: "one" when data encodes as an identifier or null, "many" when it encodes as an array, and "unshown" when the schema cannot be read (a hand-built or Schema.Unknown success).
  • In relationshipSelfLinks (src/internal/conformance/links.ts), when the relationship object carries no data, match the link's path against the declared relationship endpoints and take the cardinality from the one it resolves to. Fall back to "unshown" as today when no endpoint matches (a link to another origin, an undeclared path) or the schema says nothing.
  • Keep the SHOULD (relationship-self-matches-linkage) as it is: with no linkage there are still no identifiers to compare.

Done when

  • A links-only to-many relationship whose relationship endpoint answers one identifier fails relationship-self-dereferences, with a finding naming the declared cardinality as its source, and so does a links-only to-one relationship answering an array.
  • A links-only relationship whose link matches no declared endpoint, or whose endpoint's success schema shows no cardinality, still takes either kind, as now.
  • The three examples still pass the MUST: their paginated relationship endpoints answer arrays.
  • docs/conformance.md §3 and the fallback sentence are updated, and the rule's tests in src/Conformance.test.ts pin both the derived cardinality and the fallback.

Follow-up to #309 and #384.


Generated by Claude Code

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

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions