Repository navigation
Remove header percent-encoding based on clarifications in recent OpenAPI versions #827
Description
The question of percent-encoding header values over the evolution of the OpenAPI specification has been a bit messy, and 3.1.2 adds to it again: https://spec.openapis.org/oas/v3.1.2.html#appendix-d-serializing-headers-and-cookies
This issue tracks tracking down the correct behavior, and possibly defaulting to different behavior based on the version of the OpenAPI document - to avoid making backwards-incompatible changes.
This might require extending OpenAPI Runtime to allow customizing whether to percent-encode header values or not (maybe can even be added to the Configuration struct), and try to use the correct behavior on the newer version of OpenAPI docs where this behavior was clarified.
Activity
czechboy0 commentedon Sep 20, 2025
Seems 3.0.4 and 3.1.1 changed that, but we still percent-encode. We should stop doing that, but the question is how to do it correctly without potentially breaking existing adopters.
We could add an opt-in flag, or an opt-out flag (and fix the behavior by default), we could switch the behavior based on 3.0.3 vs 3.0.4 and 3.1.0 vs 3.1.1. Note the new ones (3.1.2, 3.2.0) even more clearly state to not perform percent encoding, and for header values that include non-standard characters, to perform encoding (eg base64) at the application level.
czechboy0 commentedon Sep 25, 2026
We should fix this, another dup: #857
[-]Investigate header percent-encoding with clarifications in recent OpenAPI versions[/-][+]Remove header percent-encoding based on clarifications in recent OpenAPI versions[/+]jordanebelanger commentedon Oct 25, 2026
@czechboy0 I ran into this when trying to set a session cookie header, I use a middleware at the moment to de-percent encode the set cookie header but it feels a bit dirty.
I've been working on a fork to add a
public var headerFieldEncoding: HeaderFieldEncodingproperty on theConfigurationobject of the swift-openapi-runtime lib. At the moment it's set to retain the percent encode behaviour by default and you need to opt out, so it should bring no breaking changes to existing users of the lib.Beforehand I looked if there were any config parameters that were dynamic based on the openapi spec version of the openapi def of the user but there seems to be no such pattern yet in the lib, perhaps something to consider? (For example if you are on 3.1.1 and up, percent encoding is opt-in instead of opt-out).
czechboy0 commentedon Oct 26, 2026
Yeah we need to do this carefully. Probably the config for percent encoding and percent decoding should be separate, as if adopters use Swift OpenAPI on both client and server, it's unlikely they can update both at the same time. So they likely first need to move to stopping percent encoding (but keeping percent decoding), and only once they've updated enough of their other components, can they move to not even percent decoding. Or they'll keep percent decoding indefinitely, just turning off percent encoding.
Of course, that has the complication that a header value might be percent encoded at the application level, and this decoding removes that, confusing the app. That said, other than doing percent decoding, what else could the application do with the string? Possibly use it as a cache key, a value used in equality comparisons, etc. So this will never be clean.
Now, ideally new users wouldn't be using percent encoding anymore, but considering the OpenAPI specification was unclear on this for many years, there are other non-Swift clients also using percent encoding. So it's unclear if anyone will ever be able to remove the percent decoding step.
What I think will be the most defensible step here, and the one that aligns us with the currently known best behavior, while avoiding likely breaks for unsuspecting users, is to:
headerPercentEncodingStrategy: HeaderPercentEncodingStrategy = [.decode](keeping.encodeout of the default).@simonjbeaumont WDYT?