Repository navigation
Aliasing query parameters #2298
Description
Consider the query parameter query in the following request:
https://my.api/api/endpoint?query=some%20query
I could document this parameter like so:
parameters:
- name: query
in: query
description: Search term
schema:
type: string
required: trueNow, our api supports a short alias for the query parameter, q:
https://my.api/api/endpoint?q=some%20query
From my research I am unable to find an explicit example of how to document this properly in OAS 3.0.
Is there already a solution to this in the spec that I have missed?
Otherwise I would suggest introducing an aliases keyword for parameters, like so:
parameters:
- name: query
aliases:
- q
in: query
description: Search term
schema:
type: string
required: trueI expect the name would be a "primary" alias and that it, together with aliases would form a list, perhaps in descending order of importance if necessary, of mutually exclusive names/aliases for the given parameter.
Activity
MikeRalphson commentedon Jul 29, 2020
Although aliasing parameter names doesn't seem to be common (I could quickly only find one definite example - https://api.open.fec.gov/swagger/ - where the aliased parameters were duplicated) that could be because of the lack of existing support, and duplicating a parameter doesn't help if it should be
required: true.I personally see some value in this for describing existing APIs, though it would add complexity to implementing the specification around detecting duplicate and overriding parameters, as well as path-parameter substitution.
mschechter-bellese commentedon Jun 25, 2021
This would be very useful for content properties as well. I use Java, and Jackson allows you to create multiple aliases for a field to ensure backward-compatibility when re-working an API.
It would be useful to provide that information at the contract level so that it's not isolated to the implementation side.
SampsonCrowley commentedon Jul 8, 2021
@MikeRalphson it's definitely less common because of lack of support
kscheirer commentedon Aug 25, 2022
I am evaluating this as a possible use case for overlays, OAI/Overlay-Specification#9.
I don't think overlays would be useful here. There is no copy operation in overlays to duplicate a parameter. An overlay could add a second parameter, but as noted this fails when "required" is true.
handrews commentedon Aug 19, 2025
With query parameters now (optionally) modeled by one schema, this (along with the comment about aliasing for "content properties" is now a JSON Schema concern. I'm pretty sure there's an issue there for such things, although idk if it's open or closed.