Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions .changeset/conformance-self-link-rules.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,11 @@
"@thomasfosterau/effect-jsonapi": minor
---

`Conformance` gains two spec-tier MUST rules on the link crawl (#309). Both use the crawl the other link rules use: same-origin only, `GET` only, 200 requests per rule, and a server error, a `429`, a `408` or a lost response leaves the link not decided. `skip: ["spec/links/"]` leaves them out with the rest.
`Conformance` gains four spec-tier rules on the link crawl (#309): two MUSTs and, as `related-dereferences` and `related-matches-linkage` split the `related` link, a SHOULD beside each. All four use the crawl the other link rules use: same-origin only, `GET` only, 200 requests per rule, and a server error, a `429`, a `408` or a lost response leaves the link not decided. Each SHOULD leaves a link its MUST fails (one that does not parse, answers a non-2xx or answers something the MUST rejects) not decided, naming that rule, so one broken link is never failed twice. `skip: ["spec/links/"]` leaves all four out with the rest.

- `spec/links/relationship-self-dereferences` follows every relationship's own `links.self` (JSON:API 1.1 §Fetching Relationships: "A server **MUST** support fetching relationship data for every relationship URL provided as a `self` link …", and "The primary data in the response document **MUST** match the appropriate value for resource linkage"). The answer must be resource linkage. When the relationship object carries linkage, the answer must hold the same identifiers. As in `spec/links/related-matches-linkage`, the check relaxes to a subset when either side carries `next`, and nothing is decided when both do.
- `spec/links/top-level-self-dereferences` follows every document's top-level `links.self` (§Fetching Resources), relationship endpoints' documents included. The answer must be a document of the same kind. A single resource must answer the same `type` and `id`, and `null` must answer `null`. A collection must answer a collection. It must hold the same resources, in any order, only when neither document carries `next` or `prev`, because a page can differ from the document it is compared with.
- `spec/links/relationship-self-dereferences` (MUST) follows every relationship's own `links.self` (JSON:API 1.1 §Fetching Relationships: "A server **MUST** support fetching relationship data for every relationship URL provided as a `self` link …", and "The primary data in the response document **MUST** match the appropriate value for resource linkage"). The answer must be resource linkage: `null`, a resource identifier object or an array of them. An identifier object carries a string `type`, a string `id` or `lid`, and nothing but those and `meta`, so full resource objects fail. The cardinality must match the relationship's linkage: `null` or one identifier for to-one, an array for to-many. A links-only relationship shows no cardinality, so it is held only to answering linkage.
- `spec/links/relationship-self-matches-linkage` (SHOULD, §Relationships: the relationship link "returns the linkage for the related resources as its primary data", with no keyword) follows the `self` of every relationship that carries linkage. The answer must name the same identifiers. As in `spec/links/related-matches-linkage`, the check relaxes to a subset when either side carries `next`, and nothing is decided when both do.
- `spec/links/top-level-self-dereferences` (MUST) follows every document's top-level `links.self` (§Fetching Resources), relationship endpoints' documents included. The answer must be resource data: a resource object, an array of them or `null`.
- `spec/links/top-level-self-matches-document` (SHOULD, §Document Top Level: `self` is "the link that generated the current response document", with no keyword) follows the same links. The answer must be a document of the same kind. A single resource must answer the same `type` and `id`, and `null` must answer `null`. A collection must answer a collection. It must hold the same resources, in any order, only when neither document carries `next` or `prev`, because a page can differ from the document it is compared with.

`Conformance.gaps` no longer lists "Relationship and top-level `self` links".
28 changes: 16 additions & 12 deletions docs/conformance.md

Large diffs are not rendered by default.

22 changes: 22 additions & 0 deletions examples/blog/test/conformance.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -107,6 +107,28 @@ describe("blog: JSON:API conformance", () => {
expect(summary.passed).toBeGreaterThan(15);
});

it("follows every relationship's and document's `self` link to a verdict", () => {
// #309: the relationship `self` link `Handlers.paginatedRelationship`
// writes for an article's comments is served by a declared
// `Endpoint.getRelationship`, so both MUSTs pass rather than skip. That
// relationship is links-only, so the relationship SHOULD has no linkage to
// compare and skips.
const ids = [
"spec/links/relationship-self-dereferences",
"spec/links/relationship-self-matches-linkage",
"spec/links/top-level-self-dereferences",
"spec/links/top-level-self-matches-document",
];
expect(
ids.map((id) => `${id}: ${report.outcomes.find((outcome) => outcome.rule.id === id)?._tag}`),
).toEqual([
"spec/links/relationship-self-dereferences: Passed",
"spec/links/relationship-self-matches-linkage: Skipped",
"spec/links/top-level-self-dereferences: Passed",
"spec/links/top-level-self-matches-document: Passed",
]);
});

it("ran the write rules against targets it created, and left nothing behind", () => {
const writeRules = [
"spec/status/create-response-document",
Expand Down
4 changes: 3 additions & 1 deletion examples/github/api.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,9 @@
* - `issues` can be created and updated (closing an issue is a state update)
* but never deleted — just like on GitHub. Issue triage happens through
* relationship endpoints: assignment (`relationships/assignee`), labelling
* (`relationships/labels`) and a paginated comment feed (`/issues/:id/comments`)
* (`relationships/labels`) and a paginated comment feed (`/issues/:id/comments`,
* whose identifiers `relationships/comments` serves — the `comments`
* relationship's `self` link)
* - `pulls` is read-only
* - `search` is a heterogeneous endpoint across repositories, issues and
* users, like GitHub's global search
Expand Down
22 changes: 22 additions & 0 deletions examples/github/test/conformance.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -136,6 +136,28 @@ describe("github: JSON:API conformance", () => {
expect(summary.passed).toBeGreaterThan(15);
});

it("follows every relationship's and document's `self` link to a verdict", () => {
// #309: the relationship `self` link `Handlers.paginatedRelationship`
// writes for an issue's comments (`/issues/:id/relationships/comments`) is served by a declared
// `Endpoint.getRelationship`, so both MUSTs pass rather than skip. That
// relationship is links-only, so the relationship SHOULD has no linkage to
// compare and skips.
const ids = [
"spec/links/relationship-self-dereferences",
"spec/links/relationship-self-matches-linkage",
"spec/links/top-level-self-dereferences",
"spec/links/top-level-self-matches-document",
];
expect(
ids.map((id) => `${id}: ${report.outcomes.find((outcome) => outcome.rule.id === id)?._tag}`),
).toEqual([
"spec/links/relationship-self-dereferences: Passed",
"spec/links/relationship-self-matches-linkage: Skipped",
"spec/links/top-level-self-dereferences: Passed",
"spec/links/top-level-self-matches-document: Passed",
]);
});

it("ran the write rules against targets it created, and left nothing behind", () => {
const writeRules = [
"spec/status/create-response-document",
Expand Down
23 changes: 23 additions & 0 deletions examples/northwind/test/conformance.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -238,6 +238,29 @@ describe("northwind: JSON:API conformance", () => {
expect(summary.passed).toBeGreaterThan(15);
});

it("follows every relationship's and document's `self` link to a verdict", () => {
// #309: the relationship `self` link `Handlers.paginatedRelationship`
// writes for an order's line items
// (`/orders/:id/relationships/lineItems`) is served by a declared
// `Endpoint.getRelationship`, so both MUSTs pass rather than skip. That
// relationship is links-only, so the relationship SHOULD has no linkage to
// compare and skips.
const ids = [
"spec/links/relationship-self-dereferences",
"spec/links/relationship-self-matches-linkage",
"spec/links/top-level-self-dereferences",
"spec/links/top-level-self-matches-document",
];
expect(
ids.map((id) => `${id}: ${report.outcomes.find((outcome) => outcome.rule.id === id)?._tag}`),
).toEqual([
"spec/links/relationship-self-dereferences: Passed",
"spec/links/relationship-self-matches-linkage: Skipped",
"spec/links/top-level-self-dereferences: Passed",
"spec/links/top-level-self-matches-document: Passed",
]);
});

it("ran the write rules against targets it created, and left nothing behind", () => {
const writeRules = [
"spec/status/create-response-document",
Expand Down
Loading
Loading