Skip to content

Implement OAI 3.0 parameter style/explode serialization - #40

Merged
noha merged 1 commit into
masterfrom
implement-parameter-style-explode-serialization
Aug 1, 2026
Merged

Implement OAI 3.0 parameter style/explode serialization#40
noha merged 1 commit into
masterfrom
implement-parameter-style-explode-serialization

Conversation

@noha

@noha noha commented Aug 1, 2026

Copy link
Copy Markdown
Contributor

style/explode were parsed and stored on OAParameter but never applied when building a request - every parameter location silently ignored them and just called value asString, which also meant:

  • Path parameters with a non-string value (e.g. a bare Integer id) crashed outright (ZnUrl>>addPathSegments: requires Strings).
  • Header/cookie array values serialized as Smalltalk's Array printString (e.g. "#(3 4 5)") instead of a comma-joined string.
  • matrix/label path styles, spaceDelimited/pipeDelimited/deepObject query styles, and explode:false were all silently no-ops.

Added a shared value-serialization layer on OAParameterLocation (isArrayValue:/isObjectValue:/explodeFor:/serializePairsFor:name: defaultStyle: and friends) implementing the full style matrix:

  • path: simple (default), label, matrix
  • query: form (default), spaceDelimited, pipeDelimited, deepObject
  • header: simple only; cookie: form only
  • explode defaults to true only for style:form, false otherwise; deepObject is only ever meaningfully defined with explode:true

Most styles produce a single serialized string; form+explode:true objects and deepObject flatten into multiple top-level query parameters instead (one pair per property), which is why serializePairsFor: returns a collection of key->value pairs rather than a single value - the query location adds each pair, while path/ header (which can never produce more than one) just take the first.

Cookies are a documented special case: the spec leaves form+ explode:true with a non-primitive value undefined for cookies (you can't repeat a cookie name the way you can repeat a query key), so arrays/objects are comma-joined into the single cookie value instead of expanded into separate pairs.

14 new tests covering the well-defined style/explode combinations, plus the two crash regressions (integer path parameter, array header/ cookie values). 27/27 OpenAPI-Client-Tests, 56/56 OpenAPI-Core-Tests, 4/4 OpenAPI-REST-Tests, 0 regressions.

style/explode were parsed and stored on OAParameter but never applied
when building a request - every parameter location silently ignored
them and just called value asString, which also meant:
- Path parameters with a non-string value (e.g. a bare Integer id)
  crashed outright (ZnUrl>>addPathSegments: requires Strings).
- Header/cookie array values serialized as Smalltalk's Array
  printString (e.g. "#(3 4 5)") instead of a comma-joined string.
- matrix/label path styles, spaceDelimited/pipeDelimited/deepObject
  query styles, and explode:false were all silently no-ops.

Added a shared value-serialization layer on OAParameterLocation
(isArrayValue:/isObjectValue:/explodeFor:/serializePairsFor:name:
defaultStyle: and friends) implementing the full style matrix:
- path: simple (default), label, matrix
- query: form (default), spaceDelimited, pipeDelimited, deepObject
- header: simple only; cookie: form only
- explode defaults to true only for style:form, false otherwise;
  deepObject is only ever meaningfully defined with explode:true

Most styles produce a single serialized string; form+explode:true
objects and deepObject flatten into multiple top-level query
parameters instead (one pair per property), which is why
serializePairsFor: returns a collection of key->value pairs rather
than a single value - the query location adds each pair, while path/
header (which can never produce more than one) just take the first.

Cookies are a documented special case: the spec leaves form+
explode:true with a non-primitive value undefined for cookies (you
can't repeat a cookie name the way you can repeat a query key), so
arrays/objects are comma-joined into the single cookie value instead
of expanded into separate pairs.

14 new tests covering the well-defined style/explode combinations,
plus the two crash regressions (integer path parameter, array header/
cookie values). 27/27 OpenAPI-Client-Tests, 56/56 OpenAPI-Core-Tests,
4/4 OpenAPI-REST-Tests, 0 regressions.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@noha
noha merged commit 9b0ad17 into master Aug 1, 2026
3 of 4 checks passed
@noha
noha deleted the implement-parameter-style-explode-serialization branch August 1, 2026 15:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant