feat(http): support deepObject query style - #11870
Conversation
|
Azure Pipelines: Successfully started running 1 pipeline(s). 1 pipeline(s) were filtered out due to trigger conditions. There may be pipelines that require an authorized user to comment /azp run to run. |
|
souloss (@souloss) please read the following Contributor License Agreement(CLA). If you agree with the CLA, please reply with the following information.
Contributor License AgreementContribution License AgreementThis Contribution License Agreement (“Agreement”) is agreed to by the party signing below (“You”),
|
4 similar comments
|
souloss (@souloss) please read the following Contributor License Agreement(CLA). If you agree with the CLA, please reply with the following information.
Contributor License AgreementContribution License AgreementThis Contribution License Agreement (“Agreement”) is agreed to by the party signing below (“You”),
|
|
souloss (@souloss) please read the following Contributor License Agreement(CLA). If you agree with the CLA, please reply with the following information.
Contributor License AgreementContribution License AgreementThis Contribution License Agreement (“Agreement”) is agreed to by the party signing below (“You”),
|
|
souloss (@souloss) please read the following Contributor License Agreement(CLA). If you agree with the CLA, please reply with the following information.
Contributor License AgreementContribution License AgreementThis Contribution License Agreement (“Agreement”) is agreed to by the party signing below (“You”),
|
|
souloss (@souloss) please read the following Contributor License Agreement(CLA). If you agree with the CLA, please reply with the following information.
Contributor License AgreementContribution License AgreementThis Contribution License Agreement (“Agreement”) is agreed to by the party signing below (“You”),
|
There was a problem hiding this comment.
🔵 Needs a closer look
The .chronus feature entry should include a short illustrative code snippet per the repo’s changelog guidelines.
Pull request overview
This PR adds first-class support for OpenAPI’s deepObject query parameter style across the TypeSpec HTTP library, the OpenAPI 3 emitter/converter, and HTTP canonicalization, with corresponding regression tests and docs/changelog updates.
Changes:
- Extend
@queryoptions withstyle: "form" | "deepObject"and defaultdeepObjecttoexplode: true. - Emit/roundtrip
deepObjectcorrectly in OpenAPI 3 (parameter attributes, conversion back to TypeSpec, and example serialization using bracket notation). - Propagate query
stylethrough HTTP canonicalization and add regression tests across packages.
File summaries
| File | Description |
|---|---|
| website/src/content/docs/docs/libraries/http/reference/data-types.md | Documents the new QueryOptions.style option and its behavior. |
| packages/openapi3/test/tsp-openapi3/parameters.test.ts | Adds OpenAPI→TypeSpec conversion coverage for deepObject and explode. |
| packages/openapi3/test/parameters.test.ts | Adds TypeSpec→OpenAPI emission coverage for deepObject and default/explicit explode. |
| packages/openapi3/test/examples.test.ts | Adds example serialization coverage for deepObject (bracket notation) and explode handling. |
| packages/openapi3/src/openapi.ts | Emits query parameter style/explode attributes for deepObject and encoded styles. |
| packages/openapi3/src/examples.ts | Serializes deepObject query examples as name[key]=value pairs. |
| packages/openapi3/src/cli/actions/convert/utils/decorators.ts | Preserves deepObject (and explode when needed) when converting OpenAPI 3 params to TypeSpec decorators. |
| packages/http/test/typekit/http-request.test.ts | Updates expectations to include default query style: "form". |
| packages/http/test/routes.test.ts | Updates URI template query parameter expectations and diagnostics coverage to include style. |
| packages/http/test/http-decorators.test.ts | Adds @query validation/behavior tests for style, including deepObject. |
| packages/http/src/parameters.ts | Sets URI-template-derived query parameter style to "form". |
| packages/http/src/http-property.ts | Expands “use-uri-template” diagnostic triggering to include query style usage. |
| packages/http/src/decorators.ts | Plumbs style through @query and applies defaults (deepObject ⇒ explode: true, default style "form"). |
| packages/http/lib/decorators.tsp | Updates the public TypeSpec decorator options model to include style. |
| packages/http/generated-defs/TypeSpec.Http.ts | Updates generated TS types to include QueryOptions.style. |
| packages/http-canonicalization/src/operation.ts | Adds query style to canonical query parameter options and propagation. |
| packages/http-canonicalization/src/operation.test.ts | Adds regression test ensuring canonicalization preserves query style. |
| .chronus/changes/support-deep-object-query-style-2026-09-07.md | Adds a changelog entry for the feature across affected packages. |
Review details
Suppressed comments (1)
.chronus/changes/support-deep-object-query-style-2026-09-07.md:10
- For
changeKind: feature, the changelog guidelines require including a short illustrative code block showing how to use the new functionality (see.github/copilot-instructions.md:139).
Add `style: "deepObject"` support to `@query` options and preserve the style when emitting or converting OpenAPI 3.
- Files reviewed: 18/18 changed files
- Comments generated: 0
- Review effort level: Lite
💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Fixes #4440
Summary
style: "form" | "deepObject"to@queryoptions.deepObjectquery parameters toexplode: trueand emit valid OpenAPI 3 parameter attributes.deepObjectwhen converting OpenAPI 3 parameters back to TypeSpec.Validation
@typespec/http: build, lint, and 414 tests passed.@typespec/openapi3: build, lint, and targeted parameter/example tests passed (478 tests).@typespec/http-canonicalization: build, lint, and 47 tests passed.