Non-ASCII characters in path literals: how should they be written, and may tooling display them decoded?

[benno-mueller-saxess]

Summary

The specification does not say how a path containing non-ASCII characters (e.g. /täst/{id})
must be written in a Paths Object key, and it does not say whether tooling may display a
percent-encoded path key in its decoded form. I would like to suggest adding both, and I am
not asking to relax the RFC 3986 alignment of the path templating ABNF.

Background

This comes out of swagger-api/swagger-ui#10367. A path like /täst/{id} breaks path parameter
substitution in Swagger UI — the request URL stays http://localhost:8080/täst/{id} instead of
.../täst/42. The issue was
closed with the
explanation that special characters in paths are not supported because they are not allowed by the
path templating ABNF,
where path-literal = 1*pchar and pchar follows
RFC 3986 §3.3.

That reading of the grammar is correct, and I accept it. The gap I ran into is what the
specification does not say around it. Quotes below are from 3.2.0; the wording and the ABNF are
unchanged in v3.3-dev (src/oas.md), so this applies to the current development version too.

What is missing

1. The consequence for non-ASCII is never spelled out.

The closest existing statements are in
URL Percent-Encoding:

All API URLs MUST successfully parse and percent-decode using [[RFC3986]] rules.

and

When percent-encoding, the safest approach is to percent-encode all characters not in RFC3986's
"unreserved" set […]

Both point in the right direction, but that section is about percent-encoding parameter values
and content (RFC 6570 expansion, Parameter/Encoding/Media Type Objects), not about the literal
segments of a Paths Object key, and neither statement nor the ABNF mentions non-ASCII characters
at all. So the requirement that /täst/{id} has to be written as /t%C3%A4st/{id} is only
derivable by combining pchar with RFC 3986 — nowhere is it stated.

The practical effect: non-ASCII paths are common, because web frameworks, routers and browsers all
accept them and handle the encoding transparently. Authors therefore write /täst/{id} in their
code and generators emit it into the description unchanged. Nothing tells them it is invalid — the
validator stays quiet and the UI just fails silently. I would suggest an explicit note in the Path
Templating section: non-ASCII characters MUST be percent-encoded in Paths Object keys, with a short
example. I understand this part may belong in an issue rather than a discussion; happy to move it.

2. Nothing says the encoded and decoded forms are the same path.

This is the part I actually care about, and the reason the Swagger UI issue had no good outcome for
me. Percent-encoding the keys is the only conforming option, and I do it with a springdoc
GlobalOpenApiCustomizer
(code).
Requests then work — but the UI now renders GET /t%C3%A4st/{id}, which is considerably harder to
read for a human than GET /täst/{id}.

Tooling currently has no basis in the specification to decode it for display.
RFC 3986 §6.2.2.2 "Percent-Encoding Normalization"
permits decoding only for unreserved characters. %C3%A4 is a non-ASCII octet sequence, and its
mapping back to a displayable character is governed by
RFC 3987 §3.2 "Converting URIs to IRIs",
which guarantees that the conversion maps back to the same URI — exactly the property a renderer
needs in order to decode safely. RFC 3987 is already referenced by this specification (in the XML
Object's namespace field, and in the appendix guidance pointing at §3.1), but the URI→IRI
direction in §3.2 is not.

So my suggestion is a permissive sentence, roughly: the percent-encoded and decoded forms of a
path identify the same resource, and tooling MAY present the decoded form (per RFC 3987 §3.2) while
using the percent-encoded form on the wire. No grammar change, no new keyword, and no new
normative reference — and it unblocks readable rendering in every downstream tool.

Alternatives I considered and rejected

• Allowing non-ASCII in the ABNF (true IRI-style paths). Breaks the RFC 3986 alignment that
  adds ABNF for path templating #4244 deliberately established and would be a breaking change for every parser. Not worth it.
• A display-name field on the Path Item (or reusing summary). A new spec feature with a much
  longer discussion, and renderers would still show the path itself. More cost, less benefit than a
  reference to RFC 3987.

Question

Is the reading above correct — is percent-encoding the intended and only conforming way to describe
a path with non-ASCII characters? And would the project be open to stating the encoded/decoded
equivalence so that tooling is allowed to render the readable form?

I am happy to open a PR against v3.3-dev for either part once there is a decision.