spec-querystring-parameters

February 17, 2026 · View on GitHub

Enforces valid use of querystring parameters.

OASCompatibility
2.0❌
3.0❌
3.1❌
3.2✅

API design principles

OpenAPI 3.2 introduces the querystring parameter location for representing the full query string as a single schema (e.g. application/x-www-form-urlencoded).

This rule ensures that:

  • There is at most one querystring parameter. Parameters with in: querystring may be defined only once per path/operation parameter set.
  • No mixing querystring with query. Parameters with in: query cannot be used together with in: querystring in the same operation/path parameter set.

Configuration

OptionTypeDescription
severitystringPossible values: off, warn, error. Default error (in recommended configuration).

An example configuration:

rules:
  spec-querystring-parameters: error

Examples

Given this configuration:

rules:
  spec-querystring-parameters: error

Example of incorrect use (mixing query and querystring):

paths:
  /events:
    get:
      summary: List events
      parameters:
        - name: timezone
          in: query
          schema:
            type: string
            default: UTC
        - name: criteria
          in: querystring
          content:
            application/x-www-form-urlencoded:
              schema:
                type: object
                properties:
                  startDate: { type: string, format: date }
                  endDate: { type: string, format: date }
                  status: { type: string, enum: [scheduled, cancelled, completed] }

Example of incorrect use (multiple querystring parameters):

paths:
  /events:
    get:
      summary: List events
      parameters:
        - name: filters
          in: querystring
          content:
            application/x-www-form-urlencoded:
              schema:
                type: object
                properties:
                  startDate: { type: string, format: date }
                  status: { type: string }
        - name: pagination
          in: querystring
          content:
            application/x-www-form-urlencoded:
              schema:
                type: object
                properties:
                  limit: { type: integer }
                  offset: { type: integer }

Example of correct use (single querystring parameter, no query):

paths:
  /events:
    get:
      summary: List events
      parameters:
        - name: params
          in: querystring
          content:
            application/x-www-form-urlencoded:
              schema:
                type: object
                properties:
                  startDate: { type: string, format: date }
                  endDate: { type: string, format: date }
                  status: { type: string, enum: [scheduled, cancelled, completed] }
                  limit: { type: integer, default: 20 }
                  offset: { type: integer, default: 0 }

Resources