microsoft / microsoft/typespec
[Feature Request] HTTP: support the QUERY method (RFC 10008) and OpenAPI 3.2 `query` operation emission
- Dominant language
- Java
- Stars
- 5.9k
- Forks
- 394
- Avg merge
- 1d 23h
- Merged PRs (30d)
- 104
Description
## Clear and concise description of the problem
The HTTP `QUERY` method is now a Proposed Standard — [RFC 10008](https://www.rfc-editor.org/rfc/rfc10008.html) (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](https://github.com/microsoft/typespec/blob/main/packages/http/src/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 #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
- [x] Follow our [Code of Conduct](https://github.com/microsoft/typespec/blob/main/CODE_OF_CONDUCT.md)
- [x] Read the [docs](https://typespec.io/docs).
- [x] Search for [existing issues](https://github.com/microsoft/typespec/issues) to avoid creating duplicates.
Contributor guide
Research direction
Begin with packages/http/src/types.ts and the @typespec/openapi3 types.d.ts model, then trace the existing verb decorator and converter/emitter wiring. Confirm how HTTP verbs reach OpenAPI path-item operations and where version-specific diagnostics are tested. Done means QUERY is authorable, emits as query for OpenAPI 3.2, and is diagnosed for earlier versions.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi, typescript
- Domain
- api, backend-api-design
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100