Repository navigation
fix(Middleware): reject fields / page / filter an endpoint does not support (#261) - #313
Merged
Merged
Conversation
… not support (#261) Owner decisions on #261 (2026-10-09): - An undeclared `fields[TYPE]`, `page[…]` or `filter[…]` is a 400 naming the parameter, with the same precedence over 406/415 as `include` / `sort` (#280). `fields` is per resource type: a `fields[TYPE]` for a type the endpoint has no fieldset for, or whose type has no attribute, is unsupported for that wire key only. - `allowedQueryParameters` refuses `include`, `fields`, `sort`, `page` and `filter` with `InvalidAllowedQueryParameter`. - An empty vocabulary means unsupported: `filter: true` over no filterable field, `page: {}`, `filter: {}`, a fieldset type with no attribute. `Family` (now a runtime `FAMILIES` list in `internal/vocabulary.ts`) is the single source of truth, replacing `SPEC_FAMILIES` / `SUPPORT_FAMILIES`. `admitsNoValue` takes the wire name and reads a `fields[TYPE]` off that type's fieldset alone. `Query.Fieldset` and the `filter: true` grammar publish their vocabularies. Closes #261 Claude-Session: https://claude.ai/code/session_0187g2QpzaHqEzX8GJxiJBVc Co-Authored-By: Claude <noreply@anthropic.com>
Merged
9 tasks done
Owner
Author
|
Owner decision on O1 (2026-10-09): the strict 400 for a Generated by Claude Code |
Owner
Author
|
Owner decision on O2 (2026-10-09): reject with 400. An undeclared member of a declared Generated by Claude Code |
This was referenced Oct 9, 2026
Merged
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 #261
This implements the three owner decisions recorded on #261 on 2026-10-09. The
include/sortpart landed in #280, #283, #294, #300 and #306.fields[…],page[…]orfilter[…]. It works likeinclude/sortsince fix(Middleware): rejectinclude/sorton an endpoint that does not support them (#261) #280: one error object per offending parameter withsource.parameternaming it, the same check inMiddleware.SchemaErrors, and the same precedence over 406 / 415. Any value is rejected, an empty one included, and so is the bare name (?page=2,?filter=x,?fields=title).allowedQueryParametersrefuses the spec's family names. An entryinclude,fields,sort,pageorfilterthrowsInvalidAllowedQueryParameterwhenschemaErrorsLayer/layerWithbuilds the layer, and fromcheckQueryParameters.filter: trueon a resource with no filterable field,filter: {},page: {}, and afields[TYPE]whose resource has no attribute.fieldsis per resource type. Afields[TYPE]is supported only by its exact wire name. So a type the endpoint has no fieldset for, or one whose type has no attribute, is unsupported for that wire key only. The endpoint's otherfields[TYPE]keep decoding (/posts?fields[posts]=title&fields[tags]=rejects onlyfields[tags]). A barefieldsand afields[TYPE][…]are rejected the same way. This follows the note on #261 from the #300 review:admitsNoValuetook notype, and its "any member" struct rule would have rejectedfields[articles]beside an emptyfields[tags]. Mutation M7 below shows exactly that failure.What the spec says
Quoted from the spec source,
_format/1.1/index.mdonjson-api/json-apigh-pages(bde79ce):400 Bad Request." This is the only 400 that applies topageandfilter. Their sections only reserve the family (L1427-1428: "Thepage[query parameter family] is reserved for pagination. Servers and clients SHOULD use these parameters for pagination operations."; L1441-1442 says the same forfilter).fields, the old behaviour (ignore it and answer with every field) was itself non-compliant.fields[TYPE]query parameter." This is why support is decided perfields[TYPE].Changes
src/internal/vocabulary.tsFAMILIES(include,fields,sort,page,filter) is now the single runtime list.FamilyandisFamilyderive from it, andVocabulary's non-fieldsarm isExclude<Family, "fields">.admitsNoValue(query, name)now takes the wire name. Forfields[TYPE], it reads the property that wire name decodes into: the one of that name,Query.schema's nestedfields, or the property aSchema.encodeKeysrenames to it. Within that property it counts only a vocabulary of thattype, so a neighbouring type's fieldset never decides it. Other families behave as before.vocabularyAnnotationis exported forQuery.ts.src/Middleware.tsSPEC_FAMILIES/SUPPORT_FAMILIES/SUPPORT_FAMILY_NAMESare replaced byUNSUPPORTED: Record<Family, (parameter) => string>, an exhaustive per-family detail. Theinclude/sortdetails are unchanged.isSupportedreplaces the oldknownlist. Afieldsname is admitted only by its exact declared name or a declaredfields[prefix. Any other name admits its whole family, as before.supportedNamesdrops every declared name for whichadmitsNoValueholds.refusal) refuses spec family names with their own message ("names a query parameter family JSON:API defines …").QueryParameterOptions.allowedQueryParameters,InvalidAllowedQueryParameter,QueryParameterCheck.declared,checkQueryParameters,SchemaErrors,schemaErrorsLayer,SchemaErrorsLiveandlayerWith.src/Query.tsQuery.Fieldsetpublishes{ family: "fields", type, values }on its literal schema. When the set is empty its rejection now readsThis endpoint supports no sparse fieldset for type "tags".instead ofExpected never, on a direct decode.Query.schema'sfilter: truepublishes the grammar's filterable field names on the decoded tree's schema.Options.fields/page/filterdocs mention the 400.meta, becauseerrorMeta'sMETA_KEYSstill lists onlyinclude/sort.README.md: the "Reserved query parameters" allow-list paragraph and the "Query parameters" paragraph on spec families. No other section was touched; in particular, not the undeclared-body-members paragraph.Behaviour check: example apps
I added a temporary test (not committed) to each example. It sends every
GETendpoint, with ids1and2, through 35–47 query strings:include/sort/fields[TYPE]for every resource type, barefields,fields[nope], sevenpage[…]spellings, fivefilterspellings,unknown,fooBar. Each request went with and without a parameterisedAccept. I compared status, headers (lessdate) and body between trunk's sources and this branch's.Every changed response is an intended new 400. The script asserted that each one is a 400 whose
errorsis exactly one object, naming the probed parameter insource.parameter, with the "does not support the … parameter" detail. On trunk these requests answered 200, 404 (an id that doesn't exist: the check now runs before the handler) or 406 (the parameterisedAccept, which this 400 now takes precedence over). Responses forinclude,sort,unknownandfooBarare byte-identical. These are the newly rejected parameters per endpoint, with the ones whose responses are unchanged:blog
GET /articles:fields[articles],fields[comments],fields[people],fields[tags], barefields,fields[nope]; still decoded:filter,pageGET /articles/1:filter[…],page[…], barefields,fields[nope]; still decoded:fields[articles],fields[comments],fields[people],fields[tags]GET /articles/1/author:fields[articles],fields[comments],fields[people],fields[tags],filter[…],page[…], barefields,fields[nope]GET /articles/1/comments:fields[articles],fields[comments],fields[people],fields[tags],filter[…], barefields,fields[nope]; still decoded:pageGET /articles/1/relationships/comments:fields[articles],fields[comments],fields[people],fields[tags],filter[…], barefields,fields[nope]; still decoded:pageGET /search: barefields,fields[nope]; still decoded:fields[articles],fields[comments],fields[people],fields[tags],filter,pagegithub
GET /issues:fields[issues],fields[labels],fields[pulls],fields[repositories],fields[users], barefields,fields[nope]; still decoded:filter,pageGET /issues/1:fields[pulls],filter[…],page[…], barefields,fields[nope]; still decoded:fields[issues],fields[labels],fields[repositories],fields[users]GET /issues/1/comments:fields[issues],fields[labels],fields[pulls],fields[repositories],fields[users],filter[…], barefields,fields[nope]; still decoded:pageGET /issues/1/relationships/labels:fields[issues],fields[labels],fields[pulls],fields[repositories],fields[users],filter[…],page[…], barefields,fields[nope]GET /pulls:fields[issues],fields[labels],fields[pulls],fields[repositories],fields[users], barefields,fields[nope]; still decoded:filter,pageGET /pulls/1:fields[issues],fields[labels],fields[pulls],fields[repositories],fields[users],filter[…],page[…], barefields,fields[nope]GET /repositories:fields[issues],fields[labels],fields[pulls],fields[repositories],fields[users], barefields,fields[nope]; still decoded:filter,pageGET /repositories/1:fields[issues],fields[labels],fields[pulls],filter[…],page[…], barefields,fields[nope]; still decoded:fields[repositories],fields[users]GET /repositories/1/owner:fields[issues],fields[labels],fields[pulls],fields[repositories],fields[users],filter[…],page[…], barefields,fields[nope]GET /search:fields[pulls], barefields,fields[nope]; still decoded:fields[issues],fields[labels],fields[repositories],fields[users],filter,pageGET /users:fields[issues],fields[labels],fields[pulls],fields[repositories],fields[users],filter[…], barefields,fields[nope]; still decoded:pageGET /users/1:fields[issues],fields[labels],fields[pulls],fields[repositories],fields[users],filter[…],page[…], barefields,fields[nope]northwind
GET /categories:fields[categories],fields[customers],fields[employees],fields[orders],fields[products],fields[shippers],fields[suppliers],fields[territories],filter[…], barefields,fields[nope]; still decoded:pageGET /categories/1:fields[categories],fields[customers],fields[employees],fields[orders],fields[products],fields[shippers],fields[suppliers],fields[territories],filter[…],page[…], barefields,fields[nope]GET /customers:fields[categories],fields[customers],fields[employees],fields[orders],fields[products],fields[shippers],fields[suppliers],fields[territories], barefields,fields[nope]; still decoded:filter,pageGET /customers/1:fields[categories],fields[customers],fields[employees],fields[orders],fields[products],fields[shippers],fields[suppliers],fields[territories],filter[…],page[…], barefields,fields[nope]GET /employees:fields[categories],fields[customers],fields[employees],fields[orders],fields[products],fields[shippers],fields[suppliers],fields[territories], barefields,fields[nope]; still decoded:filter,pageGET /employees/1:fields[categories],fields[customers],fields[employees],fields[orders],fields[products],fields[shippers],fields[suppliers],fields[territories],filter[…],page[…], barefields,fields[nope]GET /employees/1/relationships/territories:fields[categories],fields[customers],fields[employees],fields[orders],fields[products],fields[shippers],fields[suppliers],fields[territories],filter[…],page[…], barefields,fields[nope]GET /orders:fields[categories],fields[customers],fields[employees],fields[orders],fields[products],fields[shippers],fields[suppliers],fields[territories], barefields,fields[nope]; still decoded:filter,pageGET /orders/1:fields[categories],fields[products],fields[suppliers],fields[territories],filter[…],page[…], barefields,fields[nope]; still decoded:fields[customers],fields[employees],fields[orders],fields[shippers]GET /orders/1/lineItems:fields[categories],fields[customers],fields[employees],fields[orders],fields[products],fields[shippers],fields[suppliers],fields[territories],filter[…], barefields,fields[nope]; still decoded:pageGET /orders/1/relationships/shipper:fields[categories],fields[customers],fields[employees],fields[orders],fields[products],fields[shippers],fields[suppliers],fields[territories],filter[…],page[…], barefields,fields[nope]GET /products:fields[categories],fields[customers],fields[employees],fields[orders],fields[products],fields[shippers],fields[suppliers],fields[territories], barefields,fields[nope]; still decoded:filter,pageGET /products/1:fields[customers],fields[employees],fields[orders],fields[shippers],fields[territories],filter[…],page[…], barefields,fields[nope]; still decoded:fields[categories],fields[products],fields[suppliers]GET /products/1/supplier:fields[categories],fields[customers],fields[employees],fields[orders],fields[products],fields[shippers],fields[suppliers],fields[territories],filter[…],page[…], barefields,fields[nope]GET /search:fields[employees],fields[orders],fields[shippers],fields[territories], barefields,fields[nope]; still decoded:fields[categories],fields[customers],fields[products],fields[suppliers],filter,pageGET /shippers:fields[categories],fields[customers],fields[employees],fields[orders],fields[products],fields[shippers],fields[suppliers],fields[territories],filter[…], barefields,fields[nope]; still decoded:pageGET /shippers/1:fields[categories],fields[customers],fields[employees],fields[orders],fields[products],fields[shippers],fields[suppliers],fields[territories],filter[…],page[…], barefields,fields[nope]GET /suppliers:fields[categories],fields[customers],fields[employees],fields[orders],fields[products],fields[shippers],fields[suppliers],fields[territories], barefields,fields[nope]; still decoded:filter,pageGET /suppliers/1:fields[categories],fields[customers],fields[employees],fields[orders],fields[products],fields[shippers],fields[suppliers],fields[territories],filter[…],page[…], barefields,fields[nope]GET /territories:fields[categories],fields[customers],fields[employees],fields[orders],fields[products],fields[shippers],fields[suppliers],fields[territories], barefields,fields[nope]; still decoded:filter,pageGET /territories/1:fields[categories],fields[customers],fields[employees],fields[orders],fields[products],fields[shippers],fields[suppliers],fields[territories],filter[…],page[…], barefields,fields[nope]"Unchanged" means every probe of that family answered byte-identically, codec 400s included. One consequence to note:
GET /orders/10248?include=employee.territories&fields[territories]=regionnow answers 400 on northwind.fields: truedeclares no fieldset for a type that only a depth-2 include path reaches. Filed as feat(Query):fields: trueshould declare a sparse fieldset for every type an include path reaches #311 (see Notes).Tests
The tests were written first, over HTTP, in
src/Middleware.query.test.ts. On unfixed trunk sources, 98 of 218 tests in that file failed: every new rejection case, the allow-list refusals, and thecheckQueryParameterscases.fields,pageandfilteran endpoint does not support (bug:?include=/?sort=on an endpoint that does not support them is ignored, though the spec makes it a 400 #261)". 22 rejection cases run under each ofMiddleware.layer,Middleware.layerWith({ allowedQueryParameters: ["lang"] })andschemaErrorsLayerbesideContentNegotiationLive. Each asserts the exact error document and that no handler ran. The cases cover:filter[…][…], all three at once.filter: trueover no filterable field,filter: {},page: {}, a fieldset type with no attribute.fields: a type with no fieldset, an empty-vocabulary type beside a supported one, a barefieldsand afields[TYPE][x]beside declared fieldsets, another type than the fetch declares.DELETEwith no query schema;sort/unknown;queryasserted;pagefamily still dropped;layerHostNegotiated.Middleware.layerandschemaErrorsLayerbesideContentNegotiationLive: an undeclaredpage[limit]and an empty-vocabularyfilter[name]win over the 406; an empty-vocabularyfields[tags]and an undeclaredfields[posts]win over the 415. Each test also checks the 406 / 415 without the parameter.SchemaErrorsLive):tagsis non-empty;pagemember;Schema.suspendquery;"fields[tags]";Schema.encodeKeys, and a non-empty one;fields[record;Schema.Record(Schema.String, …), for which the whole check stands aside:?fields[x]=a&page[y]=b&filter[z]=canswers 200.schemaErrorsLayer,layerWithandcheckQueryParameters.checkQueryParameters: the three families undeclared;fields[TYPE]admitted only by its own name or afields[prefix.include/sorttests from docs, test: #280 review follow-ups (include / sort 400 citations, precedence tests) #283 / fix: treat an include / sort with an empty vocabulary as unsupported (#282) #294 are gone, because those layers now throw at build time. Their replacement is the refusal cases. They covered "admits a family listed inallowedQueryParameters, which the endpoint then ignores", "still decodes a family listed …" and "says the endpoint supports none when an allow-listed empty vocabulary rejects a value". That codec detail is now reachable only on a direct decode, whichsrc/Query.test.tsstill covers. The old "still ignores the undeclared?fields[people]=…" case is reversed into the new block.src/Query.test.ts: the newQuery.Fieldsetempty-set detail (direct, and throughQuery.schema), plus a non-empty control.Mutation checks
Each row applied one mutation to the final code, ran
vp test run src/Middleware.query.test.ts src/Query.test.ts src/Middleware.test.ts(482 tests), then reverted it.Middleware.query.test.tsalone)fieldsmatched per family, not per wire keyfields,fields[TYPE][x], thecheckQueryParametersper-key case, …)fields[prefix not honouredcheckQueryParametersprefix case, the openfields[record)fields/page/filteralways known (trunk'sSPEC_FAMILIES)typeignored (anyfieldsvocabulary counts)fields[posts]beside an emptyfields[tags]is rejected: the #300-review misclassification, ×3 layers, plus two supported cases)Query.schema's nestedfields)fields, notfields[TYPE]Query.Fieldsetpublishes nofieldsvocabularyfilter: truegrammar publishes no vocabularyfilter: trueover-no-field case, and the 406-precedence case that uses it)Warn-tier lint.
vp lintper changed file, trunk → head:Middleware.ts36 → 36,Middleware.query.test.ts1 → 1,Query.ts144 → 144,Query.test.ts63 → 63,internal/vocabulary.ts0 → 0. The per-rule counts are identical too. I removed two new sites I had introduced (imperative-loops,avoid-native-object-helpers), oneascast and oneT | undefined.Declarations.
dist/*.d.tsgains no bareimport "effect/…"lines. None of the new internals (FAMILIES,isFamily,vocabularyAnnotation) appears in the emitted declarations. TheFamily/isFamilythere areResource's own.Verification
All gates ran in a fresh clone, one at a time, in AGENTS.md order, on the tree committed as the head commit:
pnpm install --frozen-lockfile: passvp run build: pass ("Build complete")vp check: pass ("Found 0 errors and 4332 warnings in 132 files": existing warn-tier debt; no per-file or per-rule 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: 2817 tests. Examples: 45 / 41 / 54. The conformance kit still passes against all three, with unchangedKNOWN_FAILURES.vp run docgen(every JSDoc@examplecompiled and executed): pass ("Docs generation succeeded!", "every class example compiled and ran")fallow audit --base origin/trunk: pass ("No issues in 10 changed files"; the gate excluded 3 inherited findings: the duplicateSortexport,Query.schemacyclomatic 18 andMiddleware.sourceOfCRAP 43.1, none introduced here). Agent gatefallow audit --format json --quiet --explain --gate-marker agent: verdictpass(0 introduced).pnpm audit --audit-level high(CI only) was not run locally; this changes no dependency.Changeset
.changeset/reject-unsupported-fields-page-filter.md, patch. It opens with a bold Behaviour change line saying that a request that used to succeed can now answer 400. It coversfieldsper type, empty vocabularies, the allow-list refusal,checkQueryParameters, the precedence over 406 / 415 / 404, and the newQuery.Fieldsetempty-set detail.reject-unsupported-include-sort.mdsaid an allow-listedinclude/sortis admitted and thatfields/page/filterare still ignored;reject-reserved-query-parameters.mdsaidfields/page/filterare left to the schema, and its allow-list sentence didn't mention spec names;empty-vocabulary-unsupported.mdsaid an allow-list entry reaches the codec detail.Notes
Owner questions (defaults implemented, flag if you want otherwise):
include[x]beside a declaredincludeis. Examples:page[size]besideQuery.Page.Offset, orfilter[x]beside afilter: { q }map. The decision on bug:?include=/?sort=on an endpoint that does not support them is ignored, though the spec makes it a 400 #261 covers "an endpoint that doesn't support that family", so I kept these family-level and pinned it with a test. Rejecting them under the general rule would be a further behaviour change.fieldsis the exception, because its family is per type.fields[TYPE]=for a type with no attribute is now a 400. The spec gives an empty value a meaning ("An empty value indicates that no fields should be returned", L1321). I applied decision (c) and the coordinator's guidance as written: an empty vocabulary is unsupported, empty value included, as for?include=.Schema.encodeKeys, one of them empty. The AST doesn't say which property is which wire key, so the empty one'sfields[TYPE]is left to its codec (a 400 from the codec rather than this one). A single renamed fieldset is decided exactly (tested).Follow-ups filed:
fields[TYPE]/page[…]/filter[…]on an endpoint that does not support them (#261) #310: conformance rules that probefields[TYPE]/page[…]/filter[…]on an endpoint that doesn't support them, in feat(Conformance): probeinclude/sorton an endpoint that does not declare them (#261) #278's shape. The kit is untouched here because Conformance: dereferenceselfandrelatedlinks rather than only checking they are well-formed #168 is changing it.fields: trueshould declare a sparse fieldset for every type an include path reaches #311:fields: truedeclares fieldsets for the resource and its direct targets only. A type that only a depth-2 include path reaches can be included but not trimmed: itsfields[TYPE]is now a 400 rather than silently ignored. Reproduced on northwind'sGET /orders/10248?include=employee.territories&fields[territories]=region.#261's done-when:
include/sorton an endpoint that does not support them (#261) #280.fields/page/filter) was recorded on 2026-10-09 and is implemented here.include/sorton an endpoint that does not declare them (#261) #278, merged forinclude/sort.#310 extends item 3 to the families decided later. I read it as a follow-up rather than as part of #261's original done-when, hence
Closes #261. If you count it as part of item 3, change this toPart of #261.Not touched:
src/internal/schemaExt.ts,.changeset/reject-undeclared-*, the README undeclared-body-members paragraph (#304 follow-up), and the conformance kit (#168).🤖 Generated with Claude Code
Generated by Claude Code