[Feature Request] HTTP: support the QUERY method (RFC 10008) and OpenAPI 3.2 `query` operation emission

[ayush-sharaf]

Clear and concise description of the problem

The HTTP QUERY method is now a Proposed Standard — RFC 10008 (published June 2026, from draft-ietf-httpbis-safe-method-w-body). It provides safe, idempotent request semantics like GET, but carries the query in the request body — the long-standing answer to "GET with a body" / oversized query strings.

OpenAPI 3.2.0 already supports it as a first-class path-item operation (query:), alongside the new additionalOperations field.

TypeSpec currently cannot express this method:

• HttpVerb in @typespec/http is "get" | "put" | "post" | "patch" | "delete" | "head" (types.ts) — no query.
• Notably, the OpenAPI 3.2 document model in @typespec/openapi3 already includes it: OpenAPIHttpMethod3_2 = OpenAPI3HttpMethod | "query" plus additionalOperations on OpenAPIPathItem3_2 (types.d.ts). So the emitter-side representation exists — the gap is purely on the authoring side (verb decorator + HttpVerb), and presumably the converter/emit wiring.

Since @typespec/openapi3 can already emit openapi: 3.2.0 documents (openapi-versions: [3.2.0]), this seems like a natural, well-scoped completion of the existing 3.2 support.

Describe the solution you'd like

1. Add "query" to HttpVerb in @typespec/http.
2. Add a verb decorator. Naming needs design input, since @query is already the query-parameter decorator in the same namespace. Options: @httpQuery, or a generic escape hatch like @verb("query") (which would also serve issue [Feature Request] HTTP: Consider adding support in Typespec for specifying options object in paths #2866 for OPTIONS, and future methods via OpenAPI 3.2 additionalOperations).
3. Emission rules in @typespec/openapi3:
   • Target 3.2.0: emit as first-class query: operation.
   • Targets 3.0.x / 3.1.x: report a diagnostic (these versions have a closed operation set; additionalOperations is 3.2-only).
4. (Optional, symmetric) tsp-openapi3 convert: map query: operations in 3.2 documents back to the new verb.

Related: #2866 (OPTIONS verb support, design:needed) — a generic @verb(...) design could resolve both, though QUERY differs in that it deserves first-class treatment given its RFC status and first-class OpenAPI 3.2 slot.

I'm happy to contribute the implementation once the decorator naming/design is settled.

Checklist

• Follow our Code of Conduct
• Read the docs.
• Search for existing issues to avoid creating duplicates.

[github-actions]

🎯 Issue Triage

Feature request to add support for the HTTP QUERY method (RFC 10008) in TypeSpec, including a new HttpVerb entry in typespec/http, a verb decorator (naming TBD given @query is taken), and corresponding query: emission in typespec/openapi3 targeting OpenAPI 3.2.0.

Category: Feature Request
Area: lib:http

🔍 Analysis

Affected components:

• @typespec/http: HttpVerb type needs "query" added; a new HTTP verb decorator is needed
• @typespec/openapi3: Emitter needs to map the new verb to the first-class query: path item key in 3.2.0, and emit a diagnostic for 3.0.x/3.1.x targets
• @typespec/openapi3 converter: Optional — map query: back to the new TypeSpec verb

Key design challenge: The @query decorator is already the query-parameter decorator in typespec/http. Options are @httpQuery for first-class treatment or a generic @verb("query") escape hatch (which would also close #2866 for OPTIONS).

Positive signals: The OpenAPI 3.2 document model in typespec/openapi3 already has OpenAPIHttpMethod3_2 = OpenAPI3HttpMethod | "query" and additionalOperations on OpenAPIPathItem3_2, so emitter-side types are partially in place. RFC 10008 reached Proposed Standard in June 2026.

Related: #2866 — Support for HTTP OPTIONS verb (similar gap, design:needed). A shared @verb(...) design could resolve both.

📝 Suggested next steps

• Design decision on decorator naming: @httpQuery vs generic @verb("query")
• Add "query" to HttpVerb in packages/http/src/types.ts
• Add the verb decorator in typespec/http
• Wire emission in typespec/openapi3: query: key for 3.2.0, diagnostic for 3.0.x/3.1.x
• (Optional) Add converter support in tsp-openapi3 for query: → new verb
• Consider resolving [Feature Request] HTTP: Consider adding support in Typespec for specifying options object in paths #2866 in the same design pass

Generated by Agentic Triage

[timotheeguerin]

Now that it is a published standard we should definitely add support for it, as pointed out in the issue the main problem I see is the decorator name. I think there is a few other options, this makes it:

1. We reuse @query as it can only be used on model propety this technically would not conflict. This of coursec create issue with docs and potential confusion
2. New name @queryVerb(prefer of @httpQuery as both things are http)
3. Generic verb decorator @verb("query")
4. Verb namespspace

namespace Http;

namespace Verb {
  // move all verb decorators here
  extern dec get(
  extern dec post(
...
  extern dec query(
}

// Need aliases for others for back compat
alias get = Verb.get
alias post = Verb.post
...
// not for query 

can then use

@Verb.query

[ayush-sharaf]

Thanks @timotheeguerin — I prototyped a couple of the options against @typespec/compiler@1.13.0 to ground the naming discussion. Two findings:

Option 1 (reuse @query) can't be an overload — it would have to be a union target

Declaring the same decorator twice with different targets is rejected by the compiler:

extern dec mydec(target: ModelProperty);
extern dec mydec(target: Operation);

error duplicate-symbol: Duplicate name: "@mydec"

So "reuse @query" would mean widening the one declaration to extern dec query(target: ModelProperty | Operation, queryNameOrOptions?: ...) and dispatching on target kind in the implementation. That works, but it drags queryNameOrOptions into the verb position where it's meaningless — @query("filter") op search(...) would parse fine and need a runtime diagnostic. Combined with the docs/confusion concern you raised, that pushes me off option 1.

Body handling needs no changes — the verb addition is genuinely small

I'd assumed the operation builder had per-verb body rules that query would need to override (GET-no-body vs QUERY-requires-body). Verified that's not the case: today an explicit @body — or even an unannotated parameter — on a @get operation compiles without diagnostic and emits requestBody on the get operation in openapi3. The http layer is verb-agnostic about bodies, so @<queryverb> op search(filter: TaskFilter): Result gets correct body behavior for free. The whole feature reduces to: HttpVerb entry + decorator + openapi3 emitter mapping.

Preference

Given the small mechanical scope, I'd match the design scope to it: option 2 (@queryVerb) — one new decorator, no churn on the existing six, no union-target awkwardness. The Verb namespace (option 4) is the cleanest end-state and I like it long-term, but it can be introduced later non-breaking (aliases both directions), so it doesn't need to gate QUERY support now. If you'd rather land the namespace first and have @Verb.query be its motivating case, that also works — just a bigger review.

One emitter detail worth locking in whichever way naming goes: for 3.0.x/3.1.x targets a query-verb operation should be a compile-time diagnostic, not a skipped operation. We hit exactly that silent-drop failure downstream — openapi-generator with lenient validation drops an unrecognized query: path-item key from generated clients with no warning (OpenAPITools/openapi-generator#24212). TypeSpec refusing to emit an unrepresentable operation would make that class of bug impossible upstream.

Happy to put up a PR once naming is settled.