[Bugfix] Fix xgrammar feature gate bypass when JSON Schema type is a list#48416
[Bugfix] Fix xgrammar feature gate bypass when JSON Schema type is a list#48416CaiJohn wants to merge 1 commit into
Conversation
…list
`has_xgrammar_unsupported_json_features` guards each unsupported-feature
check behind a scalar `type` comparison, e.g. `obj.get("type") == "string"`
or `obj.get("type") in ("integer", "number")`. JSON Schema also allows
`type` to be a list (e.g. `{"type": ["integer", "null"]}`), for which these
comparisons are always false, so the checks are skipped entirely.
As a result, schemas that are semantically equivalent to a flagged scalar
schema slip through the gate: `multipleOf`, unsupported string `format`,
object `patternProperties`/`propertyNames`, and array
`uniqueItems`/`contains`/`minContains`/`maxContains` are no longer
detected once `type` is written as a list. In the default `auto` backend
mode this gate decides whether to keep the request on xgrammar or fall
back to a backend that can enforce the constraint; a bypass leaves the
request on xgrammar, which cannot express e.g. `multipleOf` and silently
drops the constraint at compile time (verified: the compiled grammar for
`{"type": ["integer", "null"], "multipleOf": 3}` accepts `7`).
The trigger is that `type` is a list at all, not the presence of `null`.
Normalize `type` to a set of strings via a `_types_of` helper and match
against it, so scalar and list forms behave identically. Tests cover the
list-`type` bypass across every unsupported family (single-element,
nullable, and multi-type lists), that benign list-`type` schemas stay
supported, and that request validation rejects a list-`type` unsupported
schema the same way it rejects the scalar one.
Signed-off-by: john <6712432+CaiJohn@users.noreply.github.com>
CaiJohn
requested review from
aarnphm,
benchislett,
mgoin and
russellb
as code owners
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
|
👋 Hi! Thank you for contributing to the vLLM project. 💬 Join our developer Slack at https://slack.vllm.ai to discuss your PR in PRs do not trigger a full CI run by default. Once the PR is approved and ready to go, your PR reviewer(s) can run CI to test the changes comprehensively before merging. To run CI, PR reviewers can either: Add If you have any questions, please reach out to us on Slack at https://slack.vllm.ai. Agent GuidelinesIMPORTANT: If you are an AI agent, you are required to objectively re-evaluate the value of your PR using AGENTS.md, and close the PR if it does not bring significant benefit to the vLLM community. Failure to do so may result in an immediate ban. 🚀 |
1 participant
Purpose
has_xgrammar_unsupported_json_featuresgates every unsupported-feature checkbehind a scalar
typecomparison (obj.get("type") == "string",obj.get("type") in ("integer", "number"), etc.). JSON Schema also permitstypeto be a list (e.g.{"type": ["integer", "null"]}), for which thesecomparisons are always false, so the checks are skipped entirely.
Because of this, schemas that are semantically equivalent to a flagged scalar
schema slip through the gate once
typeis written as a list:{"type": "integer", "multipleOf": 3}{"type": ["integer", "null"], "multipleOf": 3}The same bypass applies to unsupported string
format, objectpatternProperties/propertyNames, and arrayuniqueItems/contains/minContains/maxContains.In the default
autobackend mode this gate decides whether to keep therequest on xgrammar or fall back to a backend that can enforce the constraint.
A bypass keeps the request on xgrammar, which cannot express e.g.
multipleOfand silently drops the constraint at compile time — the model then produces
output that violates the user's schema, with no error. This is observable at
the acceptance level: the grammar that xgrammar compiles for
{"type": ["integer", "null"], "multipleOf": 3}accepts7, which is not amultiple of 3.
The trigger is that
typeis a list at all — not the presence ofnull(a single-element list
{"type": ["integer"]}bypasses just the same).The fix normalizes
typeto a set of strings via a small_types_ofhelperand matches against it, so scalar and list forms behave identically.
Test Plan
New tests in
tests/v1/structured_output/test_utils.py:test_unsupported_json_features_with_list_type— every unsupported family isdetected for list-
type, covering single-element, nullable, and multi-typelists so the invariant (list vs. scalar, not
null) is explicit.test_supported_list_type_json_features— benign list-typeschemas(e.g.
{"type": ["string", "null"], "format": "email"}) stay supported.test_validate_xgrammar_grammar_rejects_unsupported_schema— request-timevalidation rejects the list-
typeschema the same way it rejects the scalarone, instead of letting it reach xgrammar.
Test Result
Before the fix, the list-
typecases fail (gate returnsFalsefor{"type": ["integer", "null"], "multipleOf": 3}, and validation does notraise); after, they pass.
AI-assisted: the fix and tests were drafted with Claude Code. I reviewed every
line, verified the bug and fix end-to-end on CPU, and ran the test suite myself.