Repository navigation
CompoundFilter and BetaCompoundFilter use $recursiveRef, which breaks their recursion under OpenAPI 3.1 #585
Description
CompoundFilter refers to itself like this:
CompoundFilter:
$recursiveAnchor: true
type: object
properties:
filters:
type: array
items:
oneOf:
- $ref: "#/components/schemas/ComparisonFilter"
- $recursiveRef: "#"BetaCompoundFilter does the same.
This doesn't work under either JSON Schema draft:
- The document declares
openapi: 3.1.0, so its schemas use JSON Schema 2020-12.$recursiveRefand$recursiveAnchorbelong to draft 2019-09, and 2020-12 dropped them. A 2020-12 validator ignores them, so the secondoneOfbranch becomes{}, which matches anything. Every validComparisonFilterthen matches both branches, sooneOfrejects it. - Under 2019-09 rules,
"#"resolves against the base URI.CompoundFilterhas no$id, so"#"points at the root of the OpenAPI document, not atCompoundFilter.
Tools that check strictly reject both schemas, along with every operation that reaches them (21 operations today, including file search and vector store search). #452, #453 and #499 list this among other validator errors.
Suggested fix: use a plain $ref, which OpenAPI 3.1 allows for recursive schemas, and drop $recursiveAnchor:
CompoundFilter:
type: object
properties:
filters:
type: array
items:
oneOf:
- $ref: "#/components/schemas/ComparisonFilter"
- $ref: "#/components/schemas/CompoundFilter"Do the same for BetaCompoundFilter, pointing at #/components/schemas/BetaCompoundFilter.
Activity
genesiscode2026 commentedon Sep 27, 2026
Confirming this behavior across modern OpenAPI 3.1 toolchains.
Because the spec root declares
openapi: 3.1.0, parsers evaluate schemas against JSON Schema 2020-12 semantics. In draft 2020-12:$recursiveRefand$recursiveAnchor(from draft 2019-09) were replaced by$dynamicRefand$dynamicAnchor.$recursiveRefas an unknown extension keyword, breaking recursion in generated SDKs and contract validators.To restore standard recursive resolution under OpenAPI 3.1:
In our Release Guardian contract checks, we flag this specific draft-version keyword drift during CI before it breaks downstream client generators. If useful, I can share a quick normalization snippet.