Repository navigation
fix: treat an include / sort with an empty vocabulary as unsupported (#282) - #294
Merged
Merged
Conversation
…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>
This was referenced Oct 9, 2026
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>
This was referenced Oct 9, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 fromtrue. So every?include=/?sort=on such an endpoint gets #280's 400 withsource.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 insrc/Middleware.query.test.tsfirst and served them throughMiddleware.layer. The test API hasEndpoint.get(Tag, { include: { paths: [] } })andEndpoint.list(Tag, { include: true, sort: true }), whereTaghas no attributes and no relationships. On trunk all 10 new tests failed:?include=author,?include=a,band?sort=nameanswered 400 with"detail": "Expected never"plusmeta.includablePaths: []/meta.sortableFields: [].?include=,?sort=and?include[x]=aanswered 200.?sort=name&include=authoranswered one error, not two.Behaviour change, authorised by the owner's decision for this case only:
?include=author,?include=a,b,?sort=nameExpected never,meta.*: []This endpoint does not support the "include"/"sort" parameter. …,source.parameter, nometa?include=,?sort=(empty value)?include[x]=a(bracketed member)include[x]?sort=name&include=authorStatus,
source.parameter, the precedence over 406/415, and every endpoint whose vocabulary has at least one value are all unchanged. Themetathe 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). Theincludeandsortcodecs already publish their whole vocabulary as errormetaon their literal schema:includablePathsfromQuery.Include,sortableFieldsfrom the sort codec. WhendeclaredForbuilds an endpoint's declared names, it now walks the query schema's decoded side once per endpoint (errorMetaWithin: struct members, array elements, union members;Suspendisn'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 ownrejectQueryParameters, unchanged.Query.IncludeList(the open list) and a customincludeschema 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
allowedQueryParameterslistsincludeorsort: the family is admitted and the endpoint's codec decodes it. It also happens on a direct decode withQuery.Include,Query.SortorQuery.schema, for hosts that don't use the middleware. In those cases an empty vocabulary's literal schema now carries amessageannotation (vocabularyAnnotationsinsrc/internal/codecs.ts):This endpoint supports no include paths./This endpoint supports no sortable fields.Themetais kept. A non-empty vocabulary is unchanged (Expected "title").Changes
src/Middleware.ts:VOCABULARY_META,emptyVocabularies,childrenOf/errorMetaWithinandsupportedNames, used bydeclaredFor.SUPPORT_FAMILIEScomment,QueryParameterCheck.declared,checkQueryParameters,schemaErrorsLayerandSchemaErrorsLive.checkQueryParametersitself is unchanged. A plain-hook caller leaves an empty-vocabulary family out ofdeclared, as the middleware does.src/internal/errorMeta.ts: exportserrorMetaOf(was the privatemetaOf) and theErrorMetatype.src/internal/codecs.ts:vocabularyAnnotations, used by the sort codec.src/Query.ts:Query.Includeuses 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:include: { paths: [] }with a name, several names, an empty value and a bracketed member;include: trueover no relationships with a name and an empty value;sort: trueover no attributes with a name and an empty value. Each asserts the exact error document{ errors: [unsupported(parameter, family)] }(so nometa), and that no handler ran.meta.leaves a declared family with an empty vocabulary to its codectest pinned the behaviour the owner has now reversed, so these cases replace it.src/Query.test.ts: the reworded detail forQuery.Includeover no relationships,Query.Include(…, { paths: [] }),Query.Sort([])andQuery.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):declaredForback todeclaredNames(empty vocabularies count as declared)sortdropped fromVOCABULARY_METAsortcases and the two-family caseincludedropped fromVOCABULARY_METAincludecases and the two-family casevocabularyAnnotationswithout themessageinclude/sortstill decodesWarn-tier lint.
vp lintper changed file, trunk vs head:src/Middleware.ts37 → 37,src/Middleware.query.test.ts1 → 1,src/Query.ts144 → 144,src/Query.test.ts63 → 63,src/internal/codecs.ts32 → 32,src/internal/errorMeta.ts18 → 18. The walk lives inMiddleware.ts, noterrorMeta.ts. That's becauseerrorMeta.tsimportseffecttypes only, and a value import from theeffectbarrel there would add ano-barrel-importssite. A subpath import isn't an option either:test/entry-points.test.tspinseffectas 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: passvp 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@examplecompiled 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:SortTermunused type and the duplicateSortexport insrc/internal/codecs.ts/src/Query.ts, plus the inherited complexity findings onQuery.schema(cyclomatic 18) andMiddleware.sourceOf(CRAP 43.1), neither touched here). Agent gatefallow audit --format json --quiet --explain --gate-marker agent: verdictpass(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 droppedmeta, and the reworded codec detail. The pendingreject-unsupported-include-sort.mdhas one sentence changed, as described above.Notes
?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 undeclaredfields/page/filter, andallowedQueryParametersrefusing spec family names. Once the allow-list refusesinclude/sort, the reworded codec detail is reachable only through a direct decode.include/sorton an endpoint that does not declare them (#261) #278 is changingsrc/internal/conformance/*,src/Conformance*,docs/conformance.md).includewith no legal path can't include anything, so §Inclusion of Related Resources' "does not support theincludeparameter" fits it. The same goes forsortwith no sortable field under §Sorting / the general rule. That's the reason the same 400 applies.errorMetaOf,ErrorMetaandvocabularyAnnotationsare internal (src/internal/*).🤖 Generated with Claude Code
Generated by Claude Code