validate: flag a parameter whose type union mixes structured and scalar#1103
Merged
reuvenharrison merged 1 commit intoJul 21, 2026
mainoasdiff/oasdiff:mainfrom
validate-ambiguous-param-serializationoasdiff/oasdiff:validate-ambiguous-param-serializationCopy head branch name to clipboard
Merged
validate: flag a parameter whose type union mixes structured and scalar#1103reuvenharrison merged 1 commit intomainoasdiff/oasdiff:mainfrom validate-ambiguous-param-serializationoasdiff/oasdiff:validate-ambiguous-param-serializationCopy head branch name to clipboard
reuvenharrison merged 1 commit into
mainoasdiff/oasdiff:mainfrom
validate-ambiguous-param-serializationoasdiff/oasdiff:validate-ambiguous-param-serializationCopy head branch name to clipboard
Conversation
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #1103 +/- ##
==========================================
+ Coverage 88.92% 88.93% +0.01%
==========================================
Files 289 290 +1
Lines 14309 14361 +52
==========================================
+ Hits 12724 12772 +48
- Misses 1100 1103 +3
- Partials 485 486 +1
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
reuvenharrison
marked this pull request as draft
July 14, 2026 16:34
Collaborator
Author
|
Parked as draft: not urgent, and the parameter traversal here is being upstreamed as a generic walker (oasdiff/kin-openapi#22). When that ships in a kin release, this lint gets rebuilt on doc.WalkParameters and drops its local traversal. |
reuvenharrison
marked this pull request as ready for review
July 15, 2026 04:55
reuvenharrison
force-pushed
the
validate-ambiguous-param-serialization
branch
from
July 21, 2026 14:05
74d2a36 to
8666973
Compare
…ar (#1055) Reports at WARN when a parameter's schema type union mixes a structured type (array/object) with a scalar, whose style serialization is ambiguous (e.g. type: [array, integer]: is ?token=5 the array ["5"] or the integer 5). null is excluded (carries no serialization) and two scalars are fine. Uses openapi3.WalkParameters to visit every parameter once (components, path items, operations, callbacks, webhooks). ambiguous-parameter-serialization joins both the registry and nativeRuleIDs (it is an oasdiff-native lint, not a kin code). Fixes #1055
reuvenharrison
force-pushed
the
validate-ambiguous-param-serialization
branch
from
July 21, 2026 14:09
8666973 to
157da33
Compare
reuvenharrison
added a commit
that referenced
this pull request
Jul 22, 2026
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
reuvenharrison
added a commit
that referenced
this pull request
Jul 22, 2026
* docs: validate's duplicate-enum lint; allOf's dropped keywords VALIDATE.md predates the duplicate-enum-value lint (#1023); it joins the warning examples. ALLOF.md said some fields are "not merged" but if/then/else, dependentSchemas, and unevaluatedProperties are dropped outright, with semantic consequences; state it and link #1097. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs: validate also lints ambiguous parameter serialization (#1103) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #1055.
A parameter whose schema
typeunion mixes a structured type (array/object) with a scalar has no well-defined style serialization: fortype: [array, integer]a server cannot tell whether?token=5is["5"]or5. Valid JSON Schema, under-specified for OpenAPI serialization — sovalidatenow reports it at WARN asambiguous-parameter-serialization, an oasdiff-native lint alongsideduplicate-enum-value.Per the issue's scope:
nullis excluded from the union check — it carries no serialization, so[array, null]and[string, null]are unambiguous.[string, integer]) — both serialize as a single value.Implementation:
openapi3.WalkParameters(openapi3: add T.WalkParameters to visit every parameter in a document getkin/kin-openapi#1224, written for this): every parameter in the document exactly once — components, path items, operations, callbacks, webhooks — with$refdedup at the definition and RFC 6901 pointers as the findingSection. Mirrors howlintDuplicateEnumsusesWalkSchemas.typefield via origin tracking; the id joins the validate rule registry (validate: fixed registry of rule IDs; gate derived IDs through it #1101).schema) are skipped — no style serialization.mappingToStringMaptype change — backward-compatible).The issue's
application/x-www-form-urlencodedrequest-body extension is left as the follow-up it suggests.