Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

validate: flag a parameter whose type union mixes structured and scalar#1103

Merged
reuvenharrison merged 1 commit into
mainoasdiff/oasdiff:mainfrom
validate-ambiguous-param-serializationoasdiff/oasdiff:validate-ambiguous-param-serializationCopy head branch name to clipboard
Jul 21, 2026
Merged

validate: flag a parameter whose type union mixes structured and scalar#1103
reuvenharrison merged 1 commit into
mainoasdiff/oasdiff:mainfrom
validate-ambiguous-param-serializationoasdiff/oasdiff:validate-ambiguous-param-serializationCopy head branch name to clipboard

Conversation

@reuvenharrison

@reuvenharrison reuvenharrison commented Jul 14, 2026

Copy link
Copy Markdown
Collaborator

Fixes #1055.

A parameter whose schema type union mixes a structured type (array/object) with a scalar has no well-defined style serialization: for type: [array, integer] a server cannot tell whether ?token=5 is ["5"] or 5. Valid JSON Schema, under-specified for OpenAPI serialization — so validate now reports it at WARN as ambiguous-parameter-serialization, an oasdiff-native lint alongside duplicate-enum-value.

Per the issue's scope:

  • null is excluded from the union check — it carries no serialization, so [array, null] and [string, null] are unambiguous.
  • Two scalars are fine ([string, integer]) — both serialize as a single value.

Implementation:

  • The traversal is kin's 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 $ref dedup at the definition and RFC 6901 pointers as the finding Section. Mirrors how lintDuplicateEnums uses WalkSchemas.
  • Source location points at the schema's type field via origin tracking; the id joins the validate rule registry (validate: fixed registry of rule IDs; gate derived IDs through it #1101).
  • Content-based parameters (no schema) are skipped — no style serialization.
  • Dependency note: bumps kin to a master pseudo-version pending the next kin release (brings the StringMap removal, hence the one-line mappingToStringMap type change — backward-compatible).

The issue's application/x-www-form-urlencoded request-body extension is left as the follow-up it suggests.

@codecov-commenter

codecov-commenter commented Jul 14, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 92.30769% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.93%. Comparing base (bc42d62) to head (157da33).
⚠️ Report is 1 commits behind head on main.

Files with missing lines Patch % Lines
validate/lint_param_serialization.go 92.15% 3 Missing and 1 partial ⚠️
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     
Flag Coverage Δ
unittests 88.93% <92.30%> (+0.01%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@reuvenharrison
reuvenharrison marked this pull request as draft July 14, 2026 16:34
@reuvenharrison

Copy link
Copy Markdown
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
reuvenharrison marked this pull request as ready for review July 15, 2026 04:55
@reuvenharrison
reuvenharrison force-pushed the validate-ambiguous-param-serialization branch from 74d2a36 to 8666973 Compare July 21, 2026 14:05
@reuvenharrison
reuvenharrison changed the base branch from main to validate-codes-migration July 21, 2026 14:05
Base automatically changed from validate-codes-migration to main July 21, 2026 14:07
…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
reuvenharrison force-pushed the validate-ambiguous-param-serialization branch from 8666973 to 157da33 Compare July 21, 2026 14:09
@reuvenharrison
reuvenharrison merged commit cfbfbc1 into main Jul 21, 2026
7 checks passed
@reuvenharrison
reuvenharrison deleted the validate-ambiguous-param-serialization branch July 21, 2026 14:10
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>
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.

validate: flag a parameter whose union schema mixes a structured type with a scalar (ambiguous serialization)

2 participants

Morty Proxy This is a proxified and sanitized view of the page, visit original site.