Fix OpenAPI 3.0 sign schema and setup payload error reporting#3
Conversation
Replace unsupported OpenAPI const usage with 3.0-compatible enums and make CLI setup report invalid workspace creation payloads explicitly instead of classifying them as network failures. Made-with: Cursor
📝 WalkthroughWalkthroughThis pull request refines the OpenAPI schema for the asset signing endpoint's Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches
🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@openapi/agentstorage.v1.yaml`:
- Around line 211-213: The OpenAPI schema currently has "type: boolean", "enum:
[false]" and "nullable: true" which will still reject null; update the enum to
explicitly include null (i.e., change the enum for the schema that contains
enum: [false] and nullable: true to include null as an allowed value) so
validators and client generators accept nulls alongside false.
In `@packages/cli/src/commands/setup.ts`:
- Around line 123-125: The current code only throws InvalidPayloadError after a
successful res.json() call, so malformed-JSON responses fall through to the
generic network error path; wrap the res.json() call in a try/catch (or use
await res.text() then attempt JSON.parse) when handling the POST /v1/workspaces
response and, on parse failure, throw InvalidPayloadError including the raw
response/text for diagnostics; update the branch that currently throws
InvalidPayloadError (the one referencing InvalidPayloadError and res.json()) to
ensure JSON parse errors are caught and re-thrown as InvalidPayloadError so they
are not misclassified as generic network errors.
| type: boolean | ||
| enum: [false] | ||
| nullable: true |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
OpenAPI 3.0.x nullable true enum specification null validation
💡 Result:
In OpenAPI 3.0.x, nullable: true means null is added to the allowed type, but all other schema constraints still apply—and those constraints can still reject null (the spec explicitly calls this out). So if you also have an enum, validation will only pass for values in that enum; therefore null must be explicitly present in the enum list for null to validate. [1][2]
Example (OAS 3.0.x):
type: string
nullable: true
enum:
- asc
- desc
- null # must be actual null, not "null"Many linters/validators enforce this behavior (nullable + enum ⇒ enum must contain null). [2][3]
Sources: OpenAPI Spec v3.0.3 on nullable semantics and constraints [1]; Swagger docs on “Nullable enums” [2]; vacuum linter rule nullable-enum-contains-null [3].
nullable: true with enum: [false] will reject null values.
In OpenAPI 3.0.x, when both nullable: true and enum are specified, null must be explicitly included in the enum array for null validation to pass. The current definition will reject null despite the nullable constraint, causing validator and client-generator mismatches.
Add null to the enum:
Suggested fix
type: boolean
- enum: [false]
+ enum: [false, null]
nullable: true📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| type: boolean | |
| enum: [false] | |
| nullable: true | |
| type: boolean | |
| enum: [false, null] | |
| nullable: true |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@openapi/agentstorage.v1.yaml` around lines 211 - 213, The OpenAPI schema
currently has "type: boolean", "enum: [false]" and "nullable: true" which will
still reject null; update the enum to explicitly include null (i.e., change the
enum for the schema that contains enum: [false] and nullable: true to include
null as an allowed value) so validators and client generators accept nulls
alongside false.
| throw new InvalidPayloadError( | ||
| "POST /v1/workspaces returned an invalid payload.", | ||
| ); |
There was a problem hiding this comment.
Non-JSON success payloads are still reported as “network error.”
InvalidPayloadError is only thrown after a successful res.json() parse. If Line 121 throws (malformed JSON), execution falls through to the generic branch and misclassifies the failure.
💡 Suggested fix
- const payload = await res.json();
+ let payload: unknown;
+ try {
+ payload = await res.json();
+ } catch {
+ throw new InvalidPayloadError(
+ "POST /v1/workspaces returned a non-JSON payload.",
+ );
+ }
if (!isCreateWorkspacePayload(payload)) {
throw new InvalidPayloadError(
"POST /v1/workspaces returned an invalid payload.",
);
}🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@packages/cli/src/commands/setup.ts` around lines 123 - 125, The current code
only throws InvalidPayloadError after a successful res.json() call, so
malformed-JSON responses fall through to the generic network error path; wrap
the res.json() call in a try/catch (or use await res.text() then attempt
JSON.parse) when handling the POST /v1/workspaces response and, on parse
failure, throw InvalidPayloadError including the raw response/text for
diagnostics; update the branch that currently throws InvalidPayloadError (the
one referencing InvalidPayloadError and res.json()) to ensure JSON parse errors
are caught and re-thrown as InvalidPayloadError so they are not misclassified as
generic network errors.
#3) Replace unsupported OpenAPI const usage with 3.0-compatible enums and make CLI setup report invalid workspace creation payloads explicitly instead of classifying them as network failures. Made-with: Cursor
1 participant
Summary: update OpenAPI sign schema for OpenAPI 3.0 compatibility and improve CLI setup invalid payload diagnostics for POST /v1/workspaces. Test plan: npm run build --prefix packages/cli.
Made with Cursor
Summary by CodeRabbit