Skip to content

openapi: allowReserved where OpenAPI 3.2 does not apply it is kept without a warning #819

Open

Description

@fuad-daoud

Problem

OpenAPI 3.2 doesn't confine allowReserved to in: query the way 3.0 and 3.1 do. Instead it says: "This field only applies to in and style values that automatically percent-encode." Some declarations therefore have no effect:

  • in: header. Header values are never URI percent-encoded.
  • in: cookie with style: cookie. That style does not percent-encode, unlike the default form style for cookies.
  • Style combinations that 3.2's serialization rules call unusable with allowReserved, such as deepObject or form with allowReserved.
openapi: 3.2.0
…
      parameters:
        - {name: h, in: header, allowReserved: true, schema: {type: string}}
        - {name: c, in: cookie, style: cookie, allowReserved: true, schema: {type: string}}

Both bindings record allowReserved: true, and no diagnostic is reported. #725 added openapi/inapplicable-location-keyword for the 3.0/3.1 rule (path, header or cookie). It deliberately leaves 3.2 silent at every location, as #628 scoped it, and TestParams_AllowReservedLocationRule's 3.2 rows pin that silence.

Expected

In a 3.2 document, warn on allowReserved at in: header, and at in: cookie with style: cookie. Keep the value as declared (invariant 2), as the 3.0/3.1 rule does. inapplicable-location-keyword fits: the document breaks no MUST, the keyword simply has no effect. The 3.2 rows of the table test then change from silent to reported.

Whether the unusable style combinations at percent-encoding locations should also warn, and under which code, is part of this issue. Settle it against the 3.2 text before implementing; a location-only rule would not catch them.

Notes

  • lowering.Ctx.DialectMinor() already answers the version question, so the rule needs no new Ctx method.
  • Like the 3.0/3.1 rule, a parameter reached through an external $ref would be judged by the root document's version and reported at its use-site pointer.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions