Sourced*

Reference

OpenAPI 3.2.1 (Sept 2026): can path params contain a slash?

· 3 min read · Sourced

  • openapi
  • spec-release
  • path-templating

No. As of OpenAPI 3.2.1 — released 2026-09-10 by the OpenAPI Initiative — the spec text says explicitly that a path parameter's value must not contain an unescaped forward slash, and that request URLs are never matched against a template using a value that includes one. This was true in practice before (URL routing has always worked this way), but 3.2.1 is the first release to spell it out in the spec's own words rather than leaving it to RFC 3986 by implication.

What exactly changed on 2026-09-10?

OpenAPI 3.2.1 is a patch release — per the official GitHub release, it makes "no significant changes" to behavior, only "corrections and clarifications to the specification text." One of the listed items is: "clarification of how paths are matched when a template variable contains a '/'." The resulting spec text, Section 4.8.2 (Path Templating), now reads: path parameter values "MUST NOT contain any unescaped 'generic syntax' characters described by RFC3986 Section 3: forward slashes (/), question marks (?), or hashes (#)," and "this means that when matching templates to request URLs, no values that include a forward slash are matched." We checked the 3.0.4 spec text for the same passage — it is not there. The explicit sentence is new to the 3.2.x line, and the "how matching works" clarification specifically is new to 3.2.1.

Why did this need a clarification?

Because "can a path parameter contain a slash" is a question people actually run into, usually while trying to model a resource whose natural ID contains one — a file path, a namespaced identifier like team/project, or a versioned document key. The instinct is to write:

/files/{filePath}:
  get:
    operationId: getFile
    parameters:
      - name: filePath
        in: path
        required: true
        schema:
          type: string

...and pass docs/2026/report.pdf as the value. Per the now-explicit spec text, that's not a supported path templating match: a request to /files/docs/2026/report.pdf will not resolve against /files/{filePath} if the router follows the spec literally, because the parameter value contains an unescaped /.

What if your resource IDs contain slashes?

Two spec-compliant options, both of which keep the identifier legible instead of hiding it behind opaque encoding:

  1. Percent-encode the slash in the client request (docs%2F2026%2Freport.pdf), so the transmitted value has no literal / character. This satisfies the spec's "no unescaped slash" rule, but not every HTTP server or proxy decodes %2F before routing — test yours before relying on it in production, since some web servers reject encoded slashes outright for security reasons.
  2. Restructure the path to use a wildcard-style catch-all instead of a single templated parameter — model the trailing segment as part of the path structure itself (a documented pattern many API gateways use, described outside the OpenAPI spec itself since 3.x path templating doesn't define catch-all syntax). This sidesteps parameter matching entirely for the variable-depth part of the path.

Neither is "wrong" per the spec — the spec only rules out the third option, which is silently expecting a plain, unescaped / inside a single {param} segment to route correctly.

Does this affect your existing spec?

Only if you already have a path parameter modeling a value that can contain a slash — check by grepping your spec for path parameters named after things like path, key, id where the underlying resource might be hierarchical (file storage APIs and namespaced-resource APIs are the common case). If none of your path parameters model slash-containing values, 3.2.1's clarification changes nothing for you; it's a documentation fix, not a behavior change, for every other API shape.

What should you do this week?

  • If you're not on 3.2.x yet, this one clarification isn't a reason to upgrade by itself — it documents existing router behavior rather than changing it. See OpenAPI 3.1 vs 3.0 for the differences that do change generated output.
  • If you do have a slash-shaped resource ID, decide between percent-encoding and a restructured path now, and test the actual behavior of your specific gateway/framework — the spec text describes matching semantics, not every implementation's encoding behavior.
  • Run your spec through the free in-browser OpenAPI validator after any path changes to confirm the templated paths still resolve as intended.

Sourced tracks the current OpenAPI spec text when generating SDKs and docs previews from your file — start a free report to see how your paths and parameters translate into generated code.