fix(spectral): catch oneOf without discriminator at all schema depths

[pengying]

Summary

Two changes that together close a hole in our spec hygiene: a Spectral rule that catches every oneOf missing a discriminator (not just top-level schemas), and the one existing violation (Card.stateReason).

Why

Stainless's Java codegen emitted the diagnostic:

Java/SchemaUnionDiscriminatorMissing — Union has object variants but no discriminator. Deserialization may be inefficient or ambiguous without a discriminator because each object variant must be tried in sequence.

Tracking it down found a single offender: Card.stateReason, which used oneOf: [$ref CardStateReason, type: 'null']. oneOf implies a tagged union — meaningful only with a discriminator — whereas this is really just a nullable enum. The idiomatic primitive for that is anyOf.

The existing spectral rule (oneOf-must-have-discriminator) didn't catch it for two reasons:

1. Scope: it only inspected $.components.schemas[?(@.oneOf)] — i.e. top-level schemas. Nested oneOf (inside properties, allOf, etc.) was invisible.
2. Severity: it was set to warn, so wouldn't have failed CI even if it had matched.

Changes

openapi/components/schemas/cards/Card.yaml

Change stateReason from oneOf → anyOf. No semantic change for consumers; just signals to codegen that this is a nullable value, not a tagged union.

 stateReason:
-  oneOf:
+  anyOf:
     - $ref: ./CardStateReason.yaml
     - type: 'null'

.spectral.yaml

Broaden oneOf-must-have-discriminator:

• Given path: $.components.schemas[?(@.oneOf)] → $..*[?(@ && @.oneOf)]. Recursive descent with a null-safe filter so it catches oneOf at any depth (nested properties, allOf members, array items, etc.) without crashing on JSON null literals (type: 'null' etc.).
• Severity: warn → error. The only existing violation is fixed in this PR, so this won't regress CI.
• Message: updated to point devs at anyOf for nullable-value cases.

Validation

• make lint exits 0 with the fix applied.
• Temporarily regressing Card.yaml back to oneOf makes spectral fail with:

  error  oneOf-must-have-discriminator
  components.schemas.Card.properties.stateReason
  

Stack

Stacked on top of #520.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
grid-flow-builder	Ready	Preview, Comment	May 29, 2026 12:19am

[pengying]

• chore(stainless): bump edition, sync resources, fix webhook discrimination #525
• fix(spectral): catch oneOf without discriminator at all schema depths #521 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[github-actions]

✱ Stainless preview builds for grid

This PR will update the grid SDKs with the following commit messages.

cli

fix(spectral): catch oneOf without discriminator at all schema depths

csharp

fix(spectral): catch oneOf without discriminator at all schema depths

go

fix(spectral): catch oneOf without discriminator at all schema depths

kotlin

fix(spectral): catch oneOf without discriminator at all schema depths

openapi

fix(spectral): catch oneOf without discriminator at all schema depths

php

fix(spectral): catch oneOf without discriminator at all schema depths

python

fix(spectral): catch oneOf without discriminator at all schema depths

ruby

fix(spectral): catch oneOf without discriminator at all schema depths

typescript

fix(spectral): catch oneOf without discriminator at all schema depths

✅ grid-typescript studio · code

Your SDK build had at least one note diagnostic.
generate ✅ → build ✅ → lint ✅ → test ✅

npm install https://pkg.stainless.com/s/grid-typescript/23edde7b90e3eb32de909ed1731f336a2b17da3e/dist.tar.gz

✅ grid-openapi studio · code

Your SDK build had at least one note diagnostic.
generate ✅

✅ grid-ruby studio · code

Your SDK build had at least one note diagnostic.
generate ✅ → build ✅ → lint ✅ → test ✅

⚠️ grid-kotlin studio · code

Your SDK build had a failure in the test CI job, which is a regression from the base state.
generate ✅ → build ✅ → lint ✅ → test ❗

⚠️ grid-python studio · code

Your SDK build had a failure in the lint CI job, which is a regression from the base state.
generate ✅ → build ✅ → lint ❗ → test ❗

pip install https://pkg.stainless.com/s/grid-python/5440131bca25eeda8e8757c99bd7ff90d0bf42df/grid-0.0.1-py3-none-any.whl

⚠️ grid-csharp studio · code

Your SDK build had a failure in the build CI job, which is a regression from the base state.
generate ⚠️ → build ❗ → lint ✅ → test ❗

⚠️ grid-go studio · code

Your SDK build had a failure in the lint CI job, which is a regression from the base state.
generate ✅ → build ✅ → lint ❗ → test ❗

go get github.com/stainless-sdks/grid-go@f4388db834f8c4453e9b5edc7c938dbcccf3c9b1

✅ grid-php studio · code

Your SDK build had at least one note diagnostic.
generate ✅ → lint ✅ → test ✅

⚠️ grid-cli studio · code

Your SDK build had a failure in the test CI job, which is a regression from the base state.
generate ⚠️ → build ⏭️ → lint ⏭️ → test ❗

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-05-29 17:05:32 UTC

[greptile-apps]

Greptile Summary

This PR strengthens the oneOf-must-have-discriminator Spectral rule to catch violations at all schema depths (not just top-level components.schemas) and promotes it from warn to error. The stateReason property in Card.yaml — the first nested violation uncovered by the broader path — is correctly changed from oneOf to anyOf since it represents a nullable value and needs no tagged-union discriminator.

• .spectral.yaml: given updated from $.components.schemas[?(@.oneOf)] to $..*[?(@ && @.oneOf)]; severity escalated to error; message updated to guide authors toward anyOf for nullable fields.
• openapi/components/schemas/cards/Card.yaml (and both compiled openapi.yaml copies): stateReason.oneOf → anyOf to fix the newly caught violation.

Confidence Score: 4/5

Safe to merge — the logic changes are correct and the schema fix is consistent across all three copies of the spec.

The rule extension and schema fix work as intended, and a spot-check of the existing oneOf usages in openapi.yaml confirms they all carry proper discriminators. Two non-blocking observations remain: $..* applied to a resolved document may match the same oneOf multiple times if the parent schema is $ref-ed from several places, and the recursive descent adds traversal work compared to the previous top-level-only query. Neither of these affects correctness for the current spec state.

.spectral.yaml — the new JSONPath expression and its interaction with Spectral's default resolved-document mode are worth a quick double-check.

Important Files Changed

Filename	Overview
.spectral.yaml	Extended oneOf-must-have-discriminator from top-level components only to all schema depths via $..*; escalated severity from warn to error. The logic is correct, but $..* on a resolved document may produce duplicate errors and adds traversal overhead on large specs.
openapi/components/schemas/cards/Card.yaml	Corrected stateReason from oneOf to anyOf for a nullable field — the right fix since anyOf is the proper construct for "value or null" when no discriminator is needed.
openapi.yaml	Compiled spec updated in sync with the Card.yaml component source; the single oneOf → anyOf change for stateReason is correct and consistent.
mintlify/openapi.yaml	Mintlify copy of the compiled spec updated identically to openapi.yaml; change is correct and in sync.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Spectral lint run] --> B[Apply oneOf-must-have-discriminator rule]
    B --> C["$..*[?(@ and @.oneOf)]"]
    C -->|Match at any depth| D[Check for discriminator field]
    D --> E{Has discriminator?}
    E -->|Yes| F[Pass]
    E -->|No| G[Error - was warn]
    H[Card.stateReason oneOf nullable] --> I[Changed to anyOf]
    I --> F

Loading

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
.spectral.yaml:71
**`$..*` traversal on the resolved document may produce duplicate violations**

Without `resolved: false`, Spectral applies this rule to the fully inlined document — every `$ref` is replaced with its full schema content before the JSONPath runs. `$..*` then traverses the expanded tree, so a single `oneOf` that is referenced in many places (e.g. `ExternalAccountInfoOneOf` or `CustomerOneOf`) will be matched once per resolved copy. If any such site lacks a discriminator, the same error will fire multiple times for what is logically one definition. Adding `resolved: false` keeps the JSONPath anchored to the literal YAML structure and avoids that duplication.

### Issue 2 of 2
.spectral.yaml:71
**Recursive descent `$..*` can be slow on large resolved specs**

The spec already contains ~92 `oneOf` usages across thousands of nodes. `$..*` visits every node in the (resolved, fully-inlined) document to apply the filter, whereas the previous `$.components.schemas[?(@.oneOf)]` only visited the top-level schema map. For large specs this can add measurable overhead to each Spectral run. Consider a more targeted path such as `$..[oneOf]` or explicit prefixes covering the locations you care about (`$.components.schemas.*`, `$.paths..schema`, etc.) if lint run time becomes an issue.

_{Reviews (1): Last reviewed commit: "fix(spectral): catch oneOf without discr..." | Re-trigger Greptile}

[pengying]

Merge activity

• May 29, 5:03 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• May 29, 5:04 PM UTC: @pengying merged this pull request with Graphite.