Skip to content

fix: treat an include / sort with an empty vocabulary as unsupported (#282) - #294

Merged
thomasfosterau merged 1 commit into
trunkfrom
issue-282-empty-vocabulary-detail
Oct 9, 2026
Merged

thomasfosterau merged 1 commit into
trunkfrom
issue-282-empty-vocabulary-detail

Conversation

@thomasfosterau

@thomasfosterau thomasfosterau commented Oct 9, 2026 •

Copy link
Copy Markdown
Owner

Summary

Closes #282

Scope follows the owner's decision on #282 (latest comment): an empty vocabulary means unsupported. If a family's vocabulary is empty, the endpoint treats it exactly like an undeclared family. That applies whether the vocabulary is declared as [] or derived as empty from true. So every ?include= / ?sort= on such an endpoint gets #280's 400 with source.parameter, including an empty value. That replaces the issue body's narrower ask, which was to reword "Expected never" only.

Premise checked over HTTP on trunk 2521e53. I wrote the new tests in src/Middleware.query.test.ts first and served them through Middleware.layer. The test API has Endpoint.get(Tag, { include: { paths: [] } }) and Endpoint.list(Tag, { include: true, sort: true }), where Tag has no attributes and no relationships. On trunk all 10 new tests failed:

  • ?include=author, ?include=a,b and ?sort=name answered 400 with "detail": "Expected never" plus meta.includablePaths: [] / meta.sortableFields: [].
  • ?include=, ?sort= and ?include[x]=a answered 200.
  • ?sort=name&include=author answered one error, not two.

Behaviour change, authorised by the owner's decision for this case only:

Request on an empty-vocabulary endpoint trunk head
?include=author, ?include=a,b, ?sort=name 400 Expected never, meta.*: [] 400 This endpoint does not support the "include"/"sort" parameter. …, source.parameter, no meta
?include=, ?sort= (empty value) 200 400, as above
?include[x]=a (bracketed member) 200 (dropped) 400 naming include[x]
?sort=name&include=author one error one error per parameter

Status, source.parameter, the precedence over 406/415, and every endpoint whose vocabulary has at least one value are all unchanged. The meta the issue body wanted kept is gone. #280's unsupported 400 carries none, and the decision says to answer "exactly like an undeclared family".

How the support check knows the vocabulary is empty (src/Middleware.ts). The include and sort codecs already publish their whole vocabulary as error meta on their literal schema: includablePaths from Query.Include, sortableFields from the sort codec. When declaredFor builds an endpoint's declared names, it now walks the query schema's decoded side once per endpoint (errorMetaWithin: struct members, array elements, union members; Suspend isn't followed). If every vocabulary the schema publishes for a family is empty, the family is dropped from the declared names (supportedNames). After that, the check is #280's own rejectQueryParameters, unchanged. Query.IncludeList (the open list) and a custom include schema publish no vocabulary, so they still count as supported. sort: [] was already never declared.

"Expected never" is reworded where it is still reachable. Over HTTP it can still happen when allowedQueryParameters lists include or sort: the family is admitted and the endpoint's codec decodes it. It also happens on a direct decode with Query.Include, Query.Sort or Query.schema, for hosts that don't use the middleware. In those cases an empty vocabulary's literal schema now carries a message annotation (vocabularyAnnotations in src/internal/codecs.ts): This endpoint supports no include paths. / This endpoint supports no sortable fields. The meta is kept. A non-empty vocabulary is unchanged (Expected "title").

Changes

  • src/Middleware.ts:
    • VOCABULARY_META, emptyVocabularies, childrenOf / errorMetaWithin and supportedNames, used by declaredFor.
    • Doc comments updated: module header, the SUPPORT_FAMILIES comment, QueryParameterCheck.declared, checkQueryParameters, schemaErrorsLayer and SchemaErrorsLive. checkQueryParameters itself is unchanged. A plain-hook caller leaves an empty-vocabulary family out of declared, as the middleware does.
  • src/internal/errorMeta.ts: exports errorMetaOf (was the private metaOf) and the ErrorMeta type.
  • src/internal/codecs.ts: vocabularyAnnotations, used by the sort codec. src/Query.ts: Query.Include uses it.
  • README.md ("Query parameters"): the sentence saying an empty-vocabulary family "still supports it" now says it gets the same 400.
  • .changeset/reject-unsupported-include-sort.md (pending, unreleased): its sentence saying an empty-vocabulary endpoint "keeps answering as before" would contradict this release. It now points to the separate entry.

Tests

  • src/Middleware.query.test.ts, inside bug: ?include= / ?sort= on an endpoint that does not support them is ignored, though the spec makes it a 400 #261's block:
    • 8 HTTP cases: include: { paths: [] } with a name, several names, an empty value and a bracketed member; include: true over no relationships with a name and an empty value; sort: true over no attributes with a name and an empty value. Each asserts the exact error document { errors: [unsupported(parameter, family)] } (so no meta), and that no handler ran.
    • A case with both families in one request (one error object each).
    • An allow-list case asserting the reworded codec details with meta.
    • The old leaves a declared family with an empty vocabulary to its codec test pinned the behaviour the owner has now reversed, so these cases replace it.
  • src/Query.test.ts: the reworded detail for Query.Include over no relationships, Query.Include(…, { paths: [] }), Query.Sort([]) and Query.schema(Tag, { sort: true }), plus a non-empty control.

Mutation checks (vp test run src/Middleware.query.test.ts src/Query.test.ts, 311 tests on head; each mutation reverted afterwards):

Mutation Failing
Unfixed trunk (Middleware tests only) 10 of 94: every new HTTP case
declaredFor back to declaredNames (empty vocabularies count as declared) 9 of 311: the 8 rejection cases and the two-family case
sort dropped from VOCABULARY_META 3: the two sort cases and the two-family case
include dropped from VOCABULARY_META 7: the six include cases and the two-family case
vocabularyAnnotations without the message 5: the allow-list case and the 4 schema-level cases
Every declared vocabulary counts as empty 2: existing tests that a non-empty include / sort still decodes
The meta walk skips arrays 9: same as the first row (the vocabulary sits under an array)

Warn-tier lint. vp lint per changed file, trunk vs head: src/Middleware.ts 37 → 37, src/Middleware.query.test.ts 1 → 1, src/Query.ts 144 → 144, src/Query.test.ts 63 → 63, src/internal/codecs.ts 32 → 32, src/internal/errorMeta.ts 18 → 18. The walk lives in Middleware.ts, not errorMeta.ts. That's because errorMeta.ts imports effect types only, and a value import from the effect barrel there would add a no-barrel-imports site. A subpath import isn't an option either: test/entry-points.test.ts pins effect as the schema entry's only external.

Verification

All run in a fresh clone on the head commit, one at a time, in AGENTS.md order:

  • pnpm install --frozen-lockfile: pass
  • vp run build: pass ("Build complete")
  • vp check: pass ("Found 0 errors and 4345 warnings in 126 files": existing warn-tier debt; no per-file count rose)
  • vp run check (sources, type-level tests, examples, emitted declarations): pass ("check: every type gate green")
  • vp run -r test:unit: pass. Root: 2506 tests. Examples: 41 / 45 / 54 (the conformance kit still passes against all three).
  • vp run docgen (every JSDoc @example compiled and executed): pass (224 examples, "Docs generation succeeded!", every class example compiled and ran)
  • fallow audit --base origin/trunk: pass ("No issues in 9 changed files"; the gate excluded 4 inherited findings: SortTerm unused type and the duplicate Sort export in src/internal/codecs.ts / src/Query.ts, plus the inherited complexity findings on Query.schema (cyclomatic 18) and Middleware.sourceOf (CRAP 43.1), neither touched here). Agent gate fallow audit --format json --quiet --explain --gate-marker agent: verdict pass (0 introduced).

Changeset

  • .changeset/empty-vocabulary-unsupported.md, patch. It opens with a bold Behaviour change line saying that a request that used to succeed (an empty ?include= / ?sort=) can now answer 400. It also covers the new detail and the dropped meta, and the reworded codec detail. The pending reject-unsupported-include-sort.md has one sentence changed, as described above.

Notes

  • Out of scope here, per the coordinator. The other two owner decisions on bug: ?include= / ?sort= on an endpoint that does not support them is ignored, though the spec makes it a 400 #261 go in a separate follow-up after this PR: a 400 for undeclared fields / page / filter, and allowedQueryParameters refusing spec family names. Once the allow-list refuses include / sort, the reworded codec detail is reachable only through a direct decode.
  • Conformance kit untouched (feat(Conformance): probe include / sort on an endpoint that does not declare them (#261) #278 is changing src/internal/conformance/*, src/Conformance*, docs/conformance.md).
  • Spec reading. An endpoint that declares include with no legal path can't include anything, so §Inclusion of Related Resources' "does not support the include parameter" fits it. The same goes for sort with no sortable field under §Sorting / the general rule. That's the reason the same 400 applies.
  • No public signature changes. errorMetaOf, ErrorMeta and vocabularyAnnotations are internal (src/internal/*).

🤖 Generated with Claude Code


Generated by Claude Code

…282)

Owner decision on #282: a family whose vocabulary is empty counts as
undeclared. `include: { paths: [] }`, `include: true` over no
relationships and `sort: true` over no attributes now get #280's
unsupported-parameter 400 naming the parameter for every `?include=` /
`?sort=`, an empty value included, instead of the codec's "Expected
never" (or a 200 for an empty value).

The support check reads each family's vocabulary from the error `meta`
its codec already publishes (`includablePaths`, `sortableFields`) on
the endpoint's query schema, and leaves a family whose every published
vocabulary is empty out of the declared names.

Where an empty vocabulary still reaches its codec (an allow-listed
family, or a direct decode), its rejection says the endpoint supports no
include paths / sortable fields rather than "Expected never".

Closes #282

Claude-Session: https://claude.ai/code/session_0187g2QpzaHqEzX8GJxiJBVc
Co-Authored-By: Claude <noreply@anthropic.com>
@thomasfosterau
thomasfosterau merged commit 4a2ba0f into trunk Oct 9, 2026
1 check passed
@thomasfosterau
thomasfosterau deleted the issue-282-empty-vocabulary-detail branch October 9, 2026 07:11
thomasfosterau pushed a commit that referenced this pull request Oct 9, 2026
…follow-up)

Follow-up to #294 (refs #282) and the shared declared-name walk (closes #297).

- The include and sort codecs publish a dedicated internal vocabulary
  annotation (src/internal/vocabulary.ts), which the error-meta renderer
  also reads, in place of the generic error-meta annotation. Its shape
  also covers the page, filter and per-type fields vocabularies.
- The support check reads only the decoded property named include / sort,
  follows unions and Schema.suspend with a visited set, and counts a family
  unsupported only when every value it can decode draws on an empty
  vocabulary. A codec with no vocabulary, or a non-empty vocabulary in any
  union member, keeps it supported.
- Middleware.ts imports declaredNames from src/internal/declaredQuery.ts
  instead of carrying its own copy.
- Tests: the hand-built queries the review reproduced, Suspend, the
  mixed-vocabulary unions, and 406/415 precedence on an empty vocabulary.
- Docs and pending changesets: allow-listed empty vocabularies are decoded
  rather than ignored; empty-vocabulary endpoints now answer 400 where they
  used to answer 406/415.

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.

bug: an include / sort with an empty vocabulary is rejected with detail "Expected never"

2 participants