lint(openapi): require enums with more than one value to be named schemas by shreyav · Pull Request #1160 · lightsparkdev/grid-api

shreyav · 2026-10-09T18:50:41Z

Independent PR on main, but it must merge after #1151, #1152, and #1155: the rule fails on every inline enum those PRs remove, so its lint check stays red until they land. On today's main it reports 31 errors; with the three merged it reports 0.

What changed

Adds the no-inline-enums Spectral rule. It flags any enum with more than one value declared inline on a schema property, directly or inside allOf, oneOf, or anyOf, including array items. Single-value enums are not flagged, because they are the discriminator tags on variant schemas that the README already requires. ErrorNNN.code enums are excluded, since SDKs surface error codes through their error type.
Exempts seven fields in the overrides block, each with the reason: OwnershipVerifyRequest.signatureScheme, PasskeyAttestation.transports, and the two wallet operation operationType fields have values that cannot be UPPER_SNAKE_CASE; SandboxCardDisputeResponse.disposition and TwoFactorResetStatus.enrollmentStatus use null as an enum member; BulkCustomerImportJobAccepted.status is a two-value subset of BulkCustomerImportJobStatus.
Adds an "Enums" section to openapi/README.md with the convention and a before/after example, which the rule's message links to.

Why

The rule turns the convention the enum PRs established into a check, so a new inline enum fails make lint instead of generating another string-typed SDK field.

Test plan

Spectral on the current main bundle: 31 no-inline-enums errors, all on fields the three open enum PRs convert.
Spectral on main plus those three PRs: 0 errors, exit code 0 with --fail-severity=error.
Removing one override entry makes the rule report that field, so the overrides are the only thing silencing it.
Redocly lint unchanged; the spec itself is not modified.

🤖 Generated with Claude Code

https://claude.ai/code/session_01MYijrrgsrFLJZ5fkmC5XwJ

vercel · 2026-10-09T18:50:44Z

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

3 Skipped Deployments

Project	Deployment	Actions	Updated
grid-cards-demo	Ignored	Preview	Oct 9, 2026 8:21pm UTC
grid-flow-builder	Ignored	Preview	Oct 9, 2026 8:21pm UTC
grid-wallet-demo	Ignored	Preview	Oct 9, 2026 8:21pm UTC

greptile-apps · 2026-10-09T18:55:33Z

Confidence Score: 4/5

[Low impact] Adds a linting rule for OpenAPI enum documentation.

The PR appears safe to merge, with two non-blocking gaps in the new lint check.

Findings

Nested enums pass lint ▶
Error fields bypass the rule ▶

Fix with agent prompt

### Issue 1
.spectral.yaml:115-118
`no-inline-enums` misses enums inside a property's `allOf`, `oneOf`, or `anyOf`. For example, `properties.status.anyOf: [{type: string, enum: [PENDING, COMPLETED]}, {type: 'null'}]` matches none of these selectors. Nested object properties and arrays of objects are also skipped.

These fields can pass lint despite the new naming rule. Walk nested schema definitions while leaving named enums and single-value tags allowed.

### Issue 2
.spectral.yaml:115
The filter excludes every field of an `ErrorNNN` schema, although the documented exception is only for `code`. Adding a multi-value enum to another field, such as `Error422.precheckErrors.items`, would silently pass this check. Limit the exception to `code` rather than skipping the entire error schema.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Adds no-inline-enums and documents the named-enum convention.

Spectral flags inline property enums with multiple values.

_{Reviews (2) · Last reviewed commit: "lint(openapi): require enums with more t..." · Reviewed by Greptile}

greptile-apps · 2026-10-09T18:55:36Z

+      - "$.components.schemas[?(!/^Error[0-9]{3}$/.test(@property))].properties[?(@.enum && @.enum.length > 1)].enum"
+      - "$.components.schemas[?(!/^Error[0-9]{3}$/.test(@property))].properties[?(@.items && @.items.enum && @.items.enum.length > 1)].items.enum"
+      - "$.components.schemas[?(!/^Error[0-9]{3}$/.test(@property))][allOf,oneOf,anyOf].*.properties[?(@.enum && @.enum.length > 1)].enum"
+      - "$.components.schemas[?(!/^Error[0-9]{3}$/.test(@property))][allOf,oneOf,anyOf].*.properties[?(@.items && @.items.enum && @.items.enum.length > 1)].items.enum"


Nested enums escape lint

The selectors miss enums inside a property's allOf, oneOf, or anyOf, nested objects, and array item objects. For example, properties.status.anyOf[0].enum: [PENDING, COMPLETED] matches none of these paths. Property-level compositions already appear in this repository, so contributors can use supported schema shapes and miss the promised lint error. Walk the nested schemas while leaving named component enums alone.

Prompt To Fix With AI

This is a comment left during a code review. Path: .spectral.yaml Line: 115-118 Comment: **Nested enums escape lint** The selectors miss enums inside a property's `allOf`, `oneOf`, or `anyOf`, nested objects, and array item objects. For example, `properties.status.anyOf[0].enum: [PENDING, COMPLETED]` matches none of these paths. Property-level compositions already appear in this repository, so contributors can use supported schema shapes and miss the promised lint error. Walk the nested schemas while leaving named component enums alone. --- For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

greptile-apps · 2026-10-09T18:55:36Z

+    severity: error
+    resolved: false
+    given:
+      - "$.components.schemas[?(!/^Error[0-9]{3}$/.test(@property))].properties[?(@.enum && @.enum.length > 1)].enum"


Error fields escape lint

The schema-name filter exempts every property of ErrorNNN, although the documented exception is only for code. A new multi-value enum on Error409.reason, for example, would pass this check without a lint error. Exclude the code paths rather than the entire error schemas.

Knowledge Base Used: Contract validation workflows

Prompt To Fix With AI

This is a comment left during a code review. Path: .spectral.yaml Line: 115 Comment: **Error fields escape lint** The schema-name filter exempts every property of `ErrorNNN`, although the documented exception is only for `code`. A new multi-value enum on `Error409.reason`, for example, would pass this check without a lint error. Exclude the `code` paths rather than the entire error schemas. **Knowledge Base Used:** [Contract validation workflows](https://app.greptile.com/lightspark/-/custom-context/knowledge-base/lightsparkdev/grid-api/-/docs/contract-validation-workflows.md) --- For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

greptile-apps · 2026-10-09T18:56:17Z

+      - "$.components.schemas[?(!/^Error[0-9]{3}$/.test(@property))].properties[?(@.enum && @.enum.length > 1)].enum"
+      - "$.components.schemas[?(!/^Error[0-9]{3}$/.test(@property))].properties[?(@.items && @.items.enum && @.items.enum.length > 1)].items.enum"
+      - "$.components.schemas[?(!/^Error[0-9]{3}$/.test(@property))][allOf,oneOf,anyOf].*.properties[?(@.enum && @.enum.length > 1)].enum"
+      - "$.components.schemas[?(!/^Error[0-9]{3}$/.test(@property))][allOf,oneOf,anyOf].*.properties[?(@.items && @.items.enum && @.items.enum.length > 1)].items.enum"


Nested enums pass lint

no-inline-enums misses enums inside a property's allOf, oneOf, or anyOf. For example, properties.status.anyOf: [{type: string, enum: [PENDING, COMPLETED]}, {type: 'null'}] matches none of these selectors. Nested object properties and arrays of objects are also skipped.

These fields can pass lint despite the new naming rule. Walk nested schema definitions while leaving named enums and single-value tags allowed.

Prompt To Fix With AI

This is a comment left during a code review. Path: .spectral.yaml Line: 115-118 Comment: **Nested enums pass lint** `no-inline-enums` misses enums inside a property's `allOf`, `oneOf`, or `anyOf`. For example, `properties.status.anyOf: [{type: string, enum: [PENDING, COMPLETED]}, {type: 'null'}]` matches none of these selectors. Nested object properties and arrays of objects are also skipped. These fields can pass lint despite the new naming rule. Walk nested schema definitions while leaving named enums and single-value tags allowed. --- For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

greptile-apps · 2026-10-09T18:56:17Z

+    severity: error
+    resolved: false
+    given:
+      - "$.components.schemas[?(!/^Error[0-9]{3}$/.test(@property))].properties[?(@.enum && @.enum.length > 1)].enum"


Error fields bypass the rule

The filter excludes every field of an ErrorNNN schema, although the documented exception is only for code. Adding a multi-value enum to another field, such as Error422.precheckErrors.items, would silently pass this check. Limit the exception to code rather than skipping the entire error schema.

Knowledge Base Used: Contract validation workflows

Prompt To Fix With AI

This is a comment left during a code review. Path: .spectral.yaml Line: 115 Comment: **Error fields bypass the rule** The filter excludes every field of an `ErrorNNN` schema, although the documented exception is only for `code`. Adding a multi-value enum to another field, such as `Error422.precheckErrors.items`, would silently pass this check. Limit the exception to `code` rather than skipping the entire error schema. **Knowledge Base Used:** [Contract validation workflows](https://app.greptile.com/lightspark/-/custom-context/knowledge-base/lightsparkdev/grid-api/-/docs/contract-validation-workflows.md) --- For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

…emas Adds the no-inline-enums Spectral rule. An enum declared inline on a property generates a plain string field in the SDKs; a component schema generates an enum type. Single-value enums stay inline because they are the discriminator tags on variant schemas, and ErrorNNN.code enums are excluded because SDKs surface error codes through their error type. Seven fields are exempted in the overrides block: four whose values cannot be UPPER_SNAKE_CASE, two that use null as an enum member, and one that is a two-value subset of another enum. The README documents the convention. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MYijrrgsrFLJZ5fkmC5XwJ

mintlify · 2026-10-09T20:20:46Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
Grid	🟢 Ready	View Preview	Oct 9, 2026, 8:22 PM

greptile-apps Bot reviewed Oct 9, 2026

View reviewed changes

shreyav changed the base branch from named-enums-webhooks to main October 9, 2026 20:20

shreyav force-pushed the named-enums-lint branch from 1eee396 to 351a4aa Compare October 9, 2026 20:21

mintlify Bot deployed to staging - mintlify October 9, 2026 20:22 View deployment

shreyav marked this pull request as draft October 9, 2026 20:26

Navigation Menu

Repository navigation

lint(openapi): require enums with more than one value to be named schemas - #1160

lint(openapi): require enums with more than one value to be named schemas#1160
shreyav wants to merge 1 commit into
mainfrom
named-enums-lint

shreyav commented Oct 9, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Oct 9, 2026 •

edited

Loading

Uh oh!

greptile-apps Bot commented Oct 9, 2026 •

edited

Loading

Uh oh!

greptile-apps Bot Oct 9, 2026

Uh oh!

greptile-apps Bot Oct 9, 2026

Uh oh!

greptile-apps Bot Oct 9, 2026

Uh oh!

greptile-apps Bot Oct 9, 2026

Uh oh!

mintlify Bot commented Oct 9, 2026 •

edited

Loading

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

shreyav commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changed

Why

Test plan

Uh oh!

vercel Bot commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

greptile-apps Bot commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Confidence Score: 4/5

Findings

Summary

Uh oh!

greptile-apps Bot Oct 9, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot Oct 9, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot Oct 9, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot Oct 9, 2026

Choose a reason for hiding this comment

Uh oh!

mintlify Bot commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

shreyav commented Oct 9, 2026 •

edited

Loading

vercel Bot commented Oct 9, 2026 •

edited

Loading

greptile-apps Bot commented Oct 9, 2026 •

edited

Loading

mintlify Bot commented Oct 9, 2026 •

edited

Loading