@zeroxsolutions/jsonapi 0.12.1 → 0.13.1

package/CHANGELOG.md

@@ -1,3 +1,33 @@
+## 0.13.1 (2026-09-30)
+
+### 🚀 Features
+
+- **jsonapi:** build the request document a client sends ([20ca1a6](https://github.com/zeroxsolutions/zeroxsolutions/commit/20ca1a6))
+
+### ❤️ Thank You
+
+- Claude Opus 5.5 (1M context)
+- Lương Văn Tú
+
+## 0.13.0 (2026-09-29)
+
+### 🩹 Fixes
+
+- ⚠️  **jsonapi:** negotiate by the four json:api server rules alone ([67f4529](https://github.com/zeroxsolutions/zeroxsolutions/commit/67f4529))
+
+### ⚠️  Breaking Changes
+
+- **jsonapi:** negotiate by the four json:api server rules alone  ([67f4529](https://github.com/zeroxsolutions/zeroxsolutions/commit/67f4529))
+  negotiateJsonApi returns null for a Content-Type that
+  is not the JSON:API media type (or absent), and for an Accept that holds
+  no JSON:API instance. A route refuses a body it cannot read through its
+  own body validation.
+
+### ❤️ Thank You
+
+- Claude Opus 5.5 (1M context)
+- Lương Văn Tú
+
 ## 0.12.1 (2026-09-28)
 
 This was a version bump only for @zeroxsolutions/jsonapi to align it with other projects, there were no code changes.

package/README.md

@@ -3,7 +3,7 @@
 The [JSON:API v1.1](https://jsonapi.org/) halves that are **not** a response body: content negotiation
 on the request, and document deserialization on the client.
 
-Everything a server puts *in* a response - the document schemas, the serializers, the `errors[]`
+Everything a server puts _in_ a response - the document schemas, the serializers, the `errors[]`
 document - is `@zeroxsolutions/response`, and the central `onError` that renders it is
 `@zeroxsolutions/server`. The **query families** are `@zeroxsolutions/query`, which speaks this
 standard's spelling (`page[limit]`, a comma-separated `sort`, the labelled `filter` grammar,
@@ -24,10 +24,10 @@ what keeps `hono` out of the package an SPA also loads.
 
 ## Entry points
 
-| Import | Use in | What it holds |
-| --- | --- | --- |
-| `@zeroxsolutions/jsonapi` | services, gateway | `negotiateJsonApi` - the whole decision, from `Content-Type`, `Accept` and the `ext` URIs this surface supports (`supportedExtensions`), to the `JsonApiError` to reject with or `null`: 415 on a write unless `Content-Type` is exactly the JSON:API media type, carrying no parameter beyond `ext`/`profile` and no `ext` outside `supportedExtensions` - a body sent with no `Content-Type` header is refused the same way; 406 unless some `Accept` member names that same servable JSON:API media type - once one does, only JSON:API members decide - or, failing that, a wildcard range weighted above zero |
-| `@zeroxsolutions/jsonapi/client` | SPA, external consumers | `deserializeDocument` (jsona), `readResource` / `readCollection` over it - the same flattening, typed off the route's own document - `readRelated` for what an `include` resolved, which no document type can name; and `ApiError`, the non-2xx a caller throws once a response has come back |
+| Import                           | Use in                  | What it holds                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| -------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@zeroxsolutions/jsonapi`        | services, gateway       | `negotiateJsonApi` - the whole decision, from `Content-Type`, `Accept` and the `ext` URIs this surface supports (`supportedExtensions`), to the `JsonApiError` to reject with or `null`: 415 where `Content-Type` is the JSON:API media type carrying a parameter beyond `ext`/`profile` or an `ext` outside `supportedExtensions`; 406 where `Accept` holds JSON:API instances and every one carries such a parameter or `ext`; nothing else |
+| `@zeroxsolutions/jsonapi/client` | SPA, external consumers | `deserializeDocument` (jsona), `readResource` / `readCollection` over it - the same flattening, typed off the route's own document - `readRelated` for what an `include` resolved, which no document type can name; `toRequestDocument`, the JSON:API request document a write sends, each relationship wrapped in its relationship object; and `ApiError`, the non-2xx a caller throws once a response has come back                         |
 
 A transport mounts the decision rather than calling it: `jsonApiContentNegotiation` is the Hono adapter
 over it, and it lives with the other framework wiring. `negotiateJsonApi` itself takes the surface's
@@ -59,19 +59,18 @@ through the same central `onError` as every other failure rather than a shape of
 offending header in `source` and, in `detail`, what the surface reads or answers in - never the value the
 caller sent, which teaches the caller nothing it did not already have.
 
-What the headers alone do not settle:
-
-- **`Content-Type` is read only where the request carries a body.** RFC 9110 gives a GET payload no defined
-  semantics, so a read route has no representation to describe; reading the header there would turn a
-  client-wide default of `application/json` into a 415 on every collection. Where the route does read one, a
-  body sent with no `Content-Type` header is refused the same way an unservable type is.
-- **Once `Accept` names the JSON:API media type at all, only those members decide.** The standard answers 406
-  when every one of them is unacceptable, and a wildcard sitting beside them does not change that. Failing
-  that, a wildcard range weighted above zero is enough.
-- **A `q` of 0 refuses that member**, the same way a parameter the media type does not allow does.
-- **An `ext` URI outside `supportedExtensions` makes that JSON:API instance unservable** - a 415 where it
-  names `Content-Type`, or dropped from the members `Accept` considers, which is a 406 where nothing else in
-  it serves. `supportedExtensions` is `negotiateJsonApi`'s fourth parameter: the extension URIs this surface
-  answers `ext` requests for, empty by default, which refuses every `ext`.
-- **An empty `Accept` is refused.** RFC 9110 12.5.1 gives an *absent* header any media type, but an empty
-  field-value is a zero-member list, and no member of it names a range this surface can answer.
+The decision is the four server rules of JSON:API v1.1 and nothing more:
+
+- **Only the JSON:API media type is judged.** A `Content-Type` naming another type, or none, and an `Accept`
+  naming no JSON:API instance, are cases the standard sets no rule for, so they pass. A body the route
+  cannot read is refused by the route's own body validation.
+- **The body is never consulted.** A `Content-Type` with a disallowed parameter is a 415 on a request with no
+  body too, because the standard's rule names the header, not the content. A runtime decides for itself
+  whether a bodyless request has a `body` (workerd hands every POST a stream), so a decision keyed on it
+  answers differently per runtime.
+- **In `Accept`, `q` is a weight, not a parameter.** An instance weighted 0 is still unmodified, so it does
+  not make the header a 406.
+- **An `ext` URI outside `supportedExtensions` makes that JSON:API instance unusable** - a 415 where it
+  names `Content-Type`, or one fewer usable member in `Accept`, which is a 406 where none is left.
+  `supportedExtensions` is `negotiateJsonApi`'s fourth parameter: the extension URIs this surface answers
+  `ext` requests for, empty by default, which refuses every `ext`.

package/dist/client/index.d.ts

@@ -1,7 +1,9 @@
 /**
- * The client half of the standard: the document a response carries, flattened once, and the failure a caller throws.
+ * The client half of the standard: the document a response carries, flattened once, the document a write sends, and
+ * the failure a caller throws.
  */
 export { ApiError } from './api-error.js';
 export { deserializeDocument } from './deserialize.js';
 export { readCollection, readRelated, readResource, type Collection, type CollectionOf, type Resource, type ResourceOf, } from './read-document.js';
+export { toRequestDocument, type RelationshipInput, type ToRequestDocument } from './request-document.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EACL,cAAc,EACd,WAAW,EACX,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,QAAQ,EACb,KAAK,UAAU,GAChB,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EACL,cAAc,EACd,WAAW,EACX,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,QAAQ,EACb,KAAK,UAAU,GAChB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/client/index.js

@@ -1,6 +1,8 @@
 /**
- * The client half of the standard: the document a response carries, flattened once, and the failure a caller throws.
+ * The client half of the standard: the document a response carries, flattened once, the document a write sends, and
+ * the failure a caller throws.
  */
 export { ApiError } from './api-error.js';
 export { deserializeDocument } from './deserialize.js';
 export { readCollection, readRelated, readResource, } from './read-document.js';
+export { toRequestDocument } from './request-document.js';

package/dist/client/request-document.d.ts

@@ -0,0 +1,43 @@
+/** One relationship as a client writes it: the related resource's identifier, `null` to clear a to-one, or a list. */
+export type RelationshipInput = {
+    readonly type: string;
+    readonly id: string;
+} | null | readonly {
+    readonly type: string;
+    readonly id: string;
+}[];
+/**
+ * The request document {@link toRequestDocument} returns: the `type`, then each member it was handed and no other, so
+ * a route's declared body checks it member by member.
+ */
+export type ToRequestDocument<T extends string, Id, A, L> = {
+    data: {
+        type: T;
+    } & ([Id] extends [string] ? {
+        id: Id;
+    } : unknown) & ([A] extends [never] ? unknown : {
+        attributes: A;
+    }) & ([L] extends [never] ? unknown : {
+        relationships: {
+            [K in keyof L]: {
+                data: L[K];
+            };
+        };
+    });
+};
+/**
+ * Builds the JSON:API request document a write sends: one resource object of `type`, its attributes, and each
+ * relationship wrapped in the relationship object the standard requires, so no caller writes `{ data: ... }` by hand.
+ *
+ * The result is typed from the call alone, and never from the type it is assigned to, so a route's declared body can
+ * refuse a document missing the `id` an update needs.
+ *
+ * @param init - `id` on an update and never on a create; the attributes the write changes; each relationship as the
+ *   related resource's identifier, `null` to clear a to-one, or a list for a to-many
+ */
+export declare function toRequestDocument<const T extends string, Id extends string | undefined = undefined, A extends object = never, const L extends Readonly<Record<string, RelationshipInput>> = never>(type: T, init: {
+    id?: Id;
+    attributes?: A;
+    relationships?: L;
+}): ToRequestDocument<T, NoInfer<Id>, NoInfer<A>, NoInfer<L>>;
+//# sourceMappingURL=request-document.d.ts.map

package/dist/client/request-document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-document.d.ts","sourceRoot":"","sources":["../../src/client/request-document.ts"],"names":[],"mappings":"AAAA,sHAAsH;AACtH,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC9C,IAAI,GACJ,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,EAAE,CAAC;AAE9D;;;GAGG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,MAAM,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI;IAC1D,IAAI,EAAE;QAAE,IAAI,EAAE,CAAC,CAAA;KAAE,GAAG,CAAC,CAAC,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG;QAAE,EAAE,EAAE,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,GAChE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,OAAO,GAAG;QAAE,UAAU,EAAE,CAAC,CAAA;KAAE,CAAC,GACnD,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,OAAO,GAAG;QAAE,aAAa,EAAE;aAAG,CAAC,IAAI,MAAM,CAAC,GAAG;gBAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAA;aAAE;SAAE,CAAA;KAAE,CAAC,CAAC;CAC3F,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,CAAC,CAAC,SAAS,MAAM,EACtB,EAAE,SAAS,MAAM,GAAG,SAAS,GAAG,SAAS,EACzC,CAAC,SAAS,MAAM,GAAG,KAAK,EACxB,KAAK,CAAC,CAAC,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,GAAG,KAAK,EAEnE,IAAI,EAAE,CAAC,EACP,IAAI,EAAE;IAAE,EAAE,CAAC,EAAE,EAAE,CAAC;IAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IAAC,aAAa,CAAC,EAAE,CAAC,CAAA;CAAE,GACnD,iBAAiB,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAe3D"}

package/dist/client/request-document.js

@@ -0,0 +1,25 @@
+/**
+ * Builds the JSON:API request document a write sends: one resource object of `type`, its attributes, and each
+ * relationship wrapped in the relationship object the standard requires, so no caller writes `{ data: ... }` by hand.
+ *
+ * The result is typed from the call alone, and never from the type it is assigned to, so a route's declared body can
+ * refuse a document missing the `id` an update needs.
+ *
+ * @param init - `id` on an update and never on a create; the attributes the write changes; each relationship as the
+ *   related resource's identifier, `null` to clear a to-one, or a list for a to-many
+ */
+export function toRequestDocument(type, init) {
+    const { id, attributes, relationships } = init;
+    const linkage = relationships === undefined
+        ? undefined
+        : Object.fromEntries(Object.entries(relationships).map(([name, data]) => [name, { data }]));
+    // The members are the ones handed, which is what the conditional type above spells.
+    return {
+        data: {
+            type,
+            ...(id === undefined ? {} : { id }),
+            ...(attributes === undefined ? {} : { attributes }),
+            ...(linkage === undefined ? {} : { relationships: linkage }),
+        },
+    };
+}

package/dist/lib/negotiation/negotiate.d.ts

@@ -1,21 +1,19 @@
 import { JsonApiError } from '@zeroxsolutions/response';
 /**
- * Framework-neutral JSON:API v1.1 content-negotiation decision computed from request headers:
- * - **415** unless `Content-Type` is exactly the JSON:API media type, carrying no parameter other than
- *   `ext`/`profile` and no `ext` URI outside `supportedExtensions`. An empty `Content-Type` means a body sent
- *   without one, and is refused the same way: a wildcard never stands in for the one type this surface reads.
- * - **406** unless some `Accept` member names that same servable JSON:API media type, or, where none does, a
- *   wildcard range weighted above zero. An extension outside `supportedExtensions` makes a JSON:API instance
- *   unservable, which is a 415 in `Content-Type` and drops that instance from `Accept`. A `q` of 0 refuses
- *   that member the same way a disallowed parameter does.
+ * JSON:API v1.1 content negotiation, decided from the request headers and nothing else. The standard's four
+ * server rules are the whole of it:
+ * - **415** where `Content-Type` is the JSON:API media type and carries a parameter other than `ext`/`profile`,
+ *   or an `ext` URI outside `supportedExtensions`.
+ * - **406** where `Accept` holds JSON:API instances and every one carries a parameter other than
+ *   `ext`/`profile`, or an `ext` URI outside `supportedExtensions`.
  *
- * An EMPTY `Accept` is refused, deliberately: RFC 9110 12.5.1 gives an ABSENT header any media type, and an
- * empty field-value is a zero-member list rather than an absent header, so nothing in it names a range this
- * surface can answer.
+ * Nothing else is refused. A `Content-Type` naming another media type, or none, and an `Accept` naming no
+ * JSON:API instance, are cases the standard sets no rule for, so a body in another type reaches the route,
+ * whose body validation refuses what it cannot read. The rules hold whether or not the request carries a
+ * body, so no runtime's idea of an empty body can change the answer.
  *
- * @param contentType - `undefined` where the request carries no content: RFC 9110 gives a GET payload no
- * defined semantics, so reading it there would make every 415 on a read route a false one. `''` means a body
- * sent with no `Content-Type` header.
+ * @param contentType - the `Content-Type` header, `undefined` where the request sent none
+ * @param accept - the `Accept` header, `undefined` where the request sent none
  * @param namespace - the vocabulary this surface's own codes carry, so a refusal reads as one of them
  * @param supportedExtensions - the extension URIs this surface answers `ext` requests for; empty by default
  * @returns the {@link JsonApiError} to reject with, or `null` when negotiation passes

package/dist/lib/negotiation/negotiate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"negotiate.d.ts","sourceRoot":"","sources":["../../../src/lib/negotiation/negotiate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,YAAY,EAAuB,MAAM,0BAA0B,CAAC;AA4B/F;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,SAAS,EAAE,MAAM,EACjB,mBAAmB,GAAE,WAAW,CAAC,MAAM,CAAa,GACnD,YAAY,GAAG,IAAI,CAuBrB"}
+{"version":3,"file":"negotiate.d.ts","sourceRoot":"","sources":["../../../src/lib/negotiation/negotiate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,YAAY,EAAuB,MAAM,0BAA0B,CAAC;AAQ/F;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,SAAS,EAAE,MAAM,EACjB,mBAAmB,GAAE,WAAW,CAAC,MAAM,CAAa,GACnD,YAAY,GAAG,IAAI,CA4BrB"}

package/dist/lib/negotiation/negotiate.js

@@ -1,64 +1,50 @@
 import { BASE_ERROR_CODES, JsonApiError, JSON_API_MEDIA_TYPE } from '@zeroxsolutions/response';
 import { extensionsOf, isJsonApiWithDisallowedParams, parseMediaType } from './media-type.js';
-/** The ranges an `Accept` member may name and still be satisfied by the one type a JSON:API surface answers in. */
-const WILDCARD_RANGES = new Set(['application/*', '*/*']);
-/** A JSON:API instance this surface can answer: weighted above zero, no parameter but ext/profile, every ext supported. */
-function isServable(parsed, supported) {
-    return (parsed.type === JSON_API_MEDIA_TYPE &&
-        parsed.weight > 0 &&
-        !isJsonApiWithDisallowedParams(parsed) &&
-        extensionsOf(parsed).every((uri) => supported.has(uri)));
+/** A JSON:API instance this surface can use: no parameter but ext/profile, and every ext supported. */
+function isUsable(parsed, supported) {
+    return !isJsonApiWithDisallowedParams(parsed) && extensionsOf(parsed).every((uri) => supported.has(uri));
 }
 /**
- * Whether an Accept header names something this surface answers in. Where it names the JSON:API media type at
- * all, only those instances decide: the standard answers 406 when every one is modified, and a wildcard beside
- * them does not change that. Otherwise a wildcard weighted above zero is enough.
- */
-function isAcceptable(accept, supported) {
-    const members = accept.split(',').map((member) => parseMediaType(member));
-    const jsonApi = members.filter((member) => member.type === JSON_API_MEDIA_TYPE);
-    if (jsonApi.length > 0)
-        return jsonApi.some((member) => isServable(member, supported));
-    return members.some((member) => WILDCARD_RANGES.has(member.type) && member.weight > 0);
-}
-/**
- * Framework-neutral JSON:API v1.1 content-negotiation decision computed from request headers:
- * - **415** unless `Content-Type` is exactly the JSON:API media type, carrying no parameter other than
- *   `ext`/`profile` and no `ext` URI outside `supportedExtensions`. An empty `Content-Type` means a body sent
- *   without one, and is refused the same way: a wildcard never stands in for the one type this surface reads.
- * - **406** unless some `Accept` member names that same servable JSON:API media type, or, where none does, a
- *   wildcard range weighted above zero. An extension outside `supportedExtensions` makes a JSON:API instance
- *   unservable, which is a 415 in `Content-Type` and drops that instance from `Accept`. A `q` of 0 refuses
- *   that member the same way a disallowed parameter does.
+ * JSON:API v1.1 content negotiation, decided from the request headers and nothing else. The standard's four
+ * server rules are the whole of it:
+ * - **415** where `Content-Type` is the JSON:API media type and carries a parameter other than `ext`/`profile`,
+ *   or an `ext` URI outside `supportedExtensions`.
+ * - **406** where `Accept` holds JSON:API instances and every one carries a parameter other than
+ *   `ext`/`profile`, or an `ext` URI outside `supportedExtensions`.
  *
- * An EMPTY `Accept` is refused, deliberately: RFC 9110 12.5.1 gives an ABSENT header any media type, and an
- * empty field-value is a zero-member list rather than an absent header, so nothing in it names a range this
- * surface can answer.
+ * Nothing else is refused. A `Content-Type` naming another media type, or none, and an `Accept` naming no
+ * JSON:API instance, are cases the standard sets no rule for, so a body in another type reaches the route,
+ * whose body validation refuses what it cannot read. The rules hold whether or not the request carries a
+ * body, so no runtime's idea of an empty body can change the answer.
  *
- * @param contentType - `undefined` where the request carries no content: RFC 9110 gives a GET payload no
- * defined semantics, so reading it there would make every 415 on a read route a false one. `''` means a body
- * sent with no `Content-Type` header.
+ * @param contentType - the `Content-Type` header, `undefined` where the request sent none
+ * @param accept - the `Accept` header, `undefined` where the request sent none
  * @param namespace - the vocabulary this surface's own codes carry, so a refusal reads as one of them
  * @param supportedExtensions - the extension URIs this surface answers `ext` requests for; empty by default
  * @returns the {@link JsonApiError} to reject with, or `null` when negotiation passes
  */
 export function negotiateJsonApi(contentType, accept, namespace, supportedExtensions = new Set()) {
-    if (contentType !== undefined && !isServable(parseMediaType(contentType, { readWeight: false }), supportedExtensions)) {
+    const content = contentType === undefined ? undefined : parseMediaType(contentType, { readWeight: false });
+    if (content?.type === JSON_API_MEDIA_TYPE && !isUsable(content, supportedExtensions)) {
         return new JsonApiError({
             // The entry FIRST: it carries no `code` today, and the explicit one has to win the day it does.
             ...BASE_ERROR_CODES.UNSUPPORTED_MEDIA_TYPE,
             code: `${namespace}.unsupported_media_type`,
             // Names what the surface reads rather than what arrived: a failure body is a client-facing projection
             // too, and echoing the caller's own value teaches it nothing it did not send.
-            detail: `This surface reads ${JSON_API_MEDIA_TYPE}.`,
+            detail: `This surface reads ${JSON_API_MEDIA_TYPE} with no parameter but a supported ext or a profile.`,
             source: { header: 'Content-Type' },
         });
     }
-    if (accept !== undefined && !isAcceptable(accept, supportedExtensions)) {
+    const instances = (accept ?? '')
+        .split(',')
+        .map((member) => parseMediaType(member))
+        .filter((member) => member.type === JSON_API_MEDIA_TYPE);
+    if (instances.length > 0 && !instances.some((instance) => isUsable(instance, supportedExtensions))) {
         return new JsonApiError({
             ...BASE_ERROR_CODES.NOT_ACCEPTABLE,
             code: `${namespace}.not_acceptable`,
-            detail: `This surface answers ${JSON_API_MEDIA_TYPE}.`,
+            detail: `This surface answers ${JSON_API_MEDIA_TYPE} with no parameter but a supported ext or a profile.`,
             source: { header: 'Accept' },
         });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeroxsolutions/jsonapi",
-  "version": "0.12.1",
+  "version": "0.13.1",
   "private": false,
   "type": "module",
   "sideEffects": false,
@@ -30,6 +30,6 @@
   "dependencies": {
     "jsona": "^1.12.0",
     "tslib": "^2.3.0",
-    "@zeroxsolutions/response": "0.14.1"
+    "@zeroxsolutions/response": "0.14.3"
   }
 }