Pattern for RSQL or similar?

[lmxrd]

Hi! I was wondering if there is any common patterns for RSQL/FIQL or similar for query parameters when wanting to do advanced filtering?

[kinqsradio]

There's no standard way: OpenAPI has no built-in notion of a query language, so an RSQL/FIQL filter is described as a plain string parameter, and the grammar lives in the description (or a link to it). The usual pattern looks like this:

components:
  parameters:
    filter:
      name: filter
      in: query
      required: false
      description: |
        RSQL filter expression. Operators: `==`, `!=`, `=lt=`, `=le=`, `=gt=`, `=ge=`, `=in=`, `=out=`.
        Combine with `;` (AND) and `,` (OR), group with parentheses.
        Filterable fields: `status`, `createdAt`, `owner.id`.
        See https://github.com/jirutka/rsql-parser for the full grammar.
      schema:
        type: string
        maxLength: 2000
      examples:
        byStatus:
          value: status==active
        combined:
          value: status=in=(active,pending);createdAt=ge=2026-01-01

A few things that help in practice:

• List the filterable fields and operators in the description, or in an extension such as x-filterable-fields that your tooling or docs can read. This is the information clients actually need, and the part a regex can't express.
• Don't try to validate the grammar with pattern. RSQL allows nested groups, which a regular expression can't match correctly. Validate it on the server with a parser and return a 400 with a clear message.
• Reuse it as a component ($ref: '#/components/parameters/filter') so every list endpoint documents it the same way.
• Encoding: ;, ,, = and parentheses are allowed in a query string, but clients should still URL-encode the value (spaces and quotes in particular). With style: form (the default for query parameters) generators already do this.
• If you need something structured instead, the common alternatives are separate parameters per field (?status=active&createdAfter=..., easiest for generated clients) or deepObject style (?filter[status]=active, described with style: deepObject and an object schema). Both give you typed client code, but they're far less expressive than RSQL.

Specs like JSON:API (filter family) and OData ($filter) take the same approach: a single string parameter, with the language defined outside the OpenAPI document.