Skip to content

Preserve length limits in body parameter definitions and map them by type - #1011

Merged
numbata merged 8 commits into
masterfrom
fix/body-param-length-limits
Nov 3, 2026
Merged

numbata merged 8 commits into
masterfrom
fix/body-param-length-limits

Conversation

@numbata

@numbata numbata commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Length limits that API authors declare with length:, such as a name capped at 50 characters, a list capped at three entries or an object capped at five keys, were missing from the generated Swagger document for request bodies, so consumers could not see the rules the API actually enforces. This change publishes those limits for string, array and object fields in request bodies, including fields inside nested objects and arrays of objects. It also makes each limit use the keyword that matches the field type, so numbers and other types no longer receive a meaningless length keyword. API owners do not need to change any declarations; the limits appear after regenerating the documentation.

Root cause

Two separate problems:

  1. For POST, PUT and PATCH, MoveParams moves body params out of parameters and rebuilds them as a schema under definitions. That rebuild copies keys through an allowlist, and the length keys were not on it. Query and path params never go through this step, which is why only body fields lost their limits. Fixes Length limits (minLength/maxLength, minItems/maxItems) are dropped from body params moved into a definition #1010.
  2. ParseParams#document_length_limits emitted minItems / maxItems for arrays and minLength / maxLength for every other type. Grape's length: validator counts characters for strings, entries for arrays and keys for hashes, and ignores any value without length. A hash or a number with length: therefore got a maxLength that has no meaning in Swagger 2.0.

What changes

  • ParseParams picks the keyword by type: minItems / maxItems for arrays, minLength / maxLength for strings, minProperties / maxProperties for objects, and nothing for other types, which Grape does not validate either.
  • MoveParams copies minLength, maxLength, minProperties and maxProperties onto body properties.
  • minItems / maxItems are copied onto the array schema itself, where they describe the number of entries, and not onto items. They live in a named array_schema_keys method next to property_keys.
  • Explicit zero minimums (min: 0) are kept; keys are copied by presence, not truthiness.
  • Nested objects and arrays of objects (Array[JSON] with a block) get the same treatment, because they go through the same conversion.
  • Fields without a length constraint keep exactly their previous schema shape.

Benefits

  • The published contract matches what Grape validates, so developers no longer discover limits through failed requests.
  • Tools that build forms, client-side validation or generated clients from the schema get the information they need.
  • The limits come from the existing length: declarations, so there is a single source of truth and nothing to repeat in documentation: options.

Drawbacks and nuances

  • Generated documents change. Anything diffing or snapshotting the Swagger JSON, and any client regenerated from it, will show new minLength / maxLength / minItems / maxItems / minProperties / maxProperties entries. Schema-aware tools may begin enforcing limits that were previously absent, and how they do so is up to each tool. API owners should review regenerated artifacts when upgrading.
  • Output also changes for non-body params. A query, path or header param of a type other than string, array or object that declares length: no longer gets minLength / maxLength, and a hash now gets minProperties / maxProperties instead. The old output was not valid for those types and Grape never enforced a length on them, but it is a visible change.
  • This only changes documentation. Grape still validates requests, and no new server-side rules are added.
  • Other keywords that ParseParams may add in the future (for example pattern or uniqueItems) still need to be added to the allowlists by hand.
  • If a body param's type resolves to a definition, the converter writes $ref and also any length keys on the same object. Swagger 2.0 ignores siblings of $ref, so those keys have no effect there. Putting length: on an entity-typed param is unusual, and description already behaves the same way.
  • The specs cover POST, PUT and PATCH. DELETE is also in move_methods, but DELETE bodies are rare and are not exercised.

Alternatives considered

  • Pass every key through instead of using an allowlist. This would prevent this class of bug, but body definitions would then also receive Grape-internal and non-schema keys (in, name, required, and so on), changing output well beyond the length limits.
  • Share one key list between the property and array paths. The two paths intentionally copy different keys, because array limits belong on the array and element keys belong on items. Merging them would risk putting item counts on items or character limits on the array.
  • Guard only in MoveParams, copying string keys just for string types. This was the first approach. It fixed body schemas but left the wrong keywords in query output and had no place for minProperties / maxProperties, so the type mapping moved to ParseParams, where the keywords are produced.
  • Ask API authors to repeat limits through documentation: options. This duplicates information that is already declared and would leave every existing API with the gap.

numbata added a commit that referenced this pull request Oct 26, 2026
@github-actions

github-actions Bot commented Oct 26, 2026 •

Copy link
Copy Markdown

Danger Report

No issues found.

View run

@numbata
numbata requested a balanced review from Copilot October 26, 2026 11:05

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

@numbata
numbata marked this pull request as ready for review October 26, 2026 11:46
@numbata
numbata requested a lite review from Copilot November 3, 2026 11:38

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues are reported, and the change includes type-appropriate constraint preservation with regression coverage for the affected body-definition cases.

No open issues 🎉

Review effort: Lite

@numbata numbata changed the title Preserve length limits in body parameter definitions Preserve length limits in body parameter definitions and map them by type Nov 3, 2026
numbata added a commit that referenced this pull request Nov 3, 2026
## Summary

The Danger check that runs on every pull request fails in CI before it
reviews anything, so contributors get no automated feedback. This change
keeps the bundle on a version of the `git` library that Danger can load,
so the check runs again. Contributors and maintainers need no change to
their workflow.

## Root cause

CI runs `bundle exec danger`. With no upper bound on `git`, the bundle
resolves `git` 6, which removed the `Git::Base` constant. Danger 9.6.1
references that constant while it loads (`scm_source/git_repo.rb:209`),
so the job exits with `uninitialized constant Git::Base` before any pull
request is checked. See the failing run on #1011:
https://github.com/ruby-grape/grape-swagger/actions/runs/41628597475/job/125892119818

## What changes

`git` is capped below 6 in the `test` group of the Gemfile, next to
`danger`, with a comment explaining why. The gem is only used by Danger,
so the constraint does not reach the gem's runtime or the supported
Grape and Ruby matrix.

## Drawbacks and nuances

- The cap needs lifting once a Danger release supports `git` 6. The fix
is in progress upstream (danger/danger#1560, with the proposed fix in
danger/danger#1561), but it is neither merged nor released; the latest
release, 9.6.1, still fails. Until then the cap holds the dependency
back on purpose.
- The `Gemfile` is not locked in this repo, so the cap takes effect on
the next resolution in CI.

## Alternatives considered

- **Wait for a Danger release that supports `git` 6.** This leaves the
check broken for every open PR in the meantime, with no release date to
plan around.
- **Point `danger` at the upstream fix branch.** Depending on an
unreviewed, unmerged pull request from a fork would be less stable than
a one-line cap.
- **Pin `danger` itself.** The failure comes from `git` 6, and an older
Danger does not guarantee it avoids the same constant.
numbata and others added 8 commits November 3, 2026 13:03
Length limits were parsed but omitted when body parameters became schema properties. Copy string and array bounds during conversion and cover POST, PUT, PATCH, nested objects, and zero minimums with regression tests.
The array path in MoveParams kept its own inline key list next to the shared
property_keys, so a new keyword has to be remembered in two spots. Naming the
array keys puts both lists side by side. The specs now cover arrays of objects
and assert the nested properties exactly.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The keys belong to the array schema itself, while property_keys is also used to build the array's items, so the old name suggested the opposite split.
A length on a Hash or Float body param would otherwise emit maxLength on an
object or number schema, where the keyword has no meaning.
Grape's length validator counts characters for strings, entries for arrays and
keys for hashes, and ignores other types. Emit minLength/maxLength only for
strings and minProperties/maxProperties for objects, so numbers and objects no
longer get a meaningless maxLength, and let body definitions carry the new keys.
@numbata
numbata force-pushed the fix/body-param-length-limits branch from 0f72479 to fd98ff9 Compare November 3, 2026 12:03
@numbata
numbata merged commit 3ac0e94 into master Nov 3, 2026
32 checks passed
@numbata
numbata deleted the fix/body-param-length-limits branch November 3, 2026 12:21
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.

Length limits (minLength/maxLength, minItems/maxItems) are dropped from body params moved into a definition

2 participants