cloudflare / cloudflare/cfssl

> I couldn't figure out how to report an issue regarding this so I opened a PR.

Open
#1,446 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Go
Stars
9.5k
Forks
1.2k
PR merge metrics
No merged PRs in 30d

Description

> I couldn't figure out how to report an issue regarding this so I opened a PR.
> gem.gemn
> ## Summary
> Remove the shared `result: object | null` constraint from `builds_APIResponse` so Workers Builds endpoints can define their own response `result` shape.
>
> ## Problem
> I encountered this while generating runtime validators from the OpenAPI schema and validating Cloudflare API responses with Ajv.
>
> `builds_APIResponse` currently defines `result` as:
>
> ```yaml
> result:
> nullable: true
> type: object
> ```
>
> and also marks `result` as required.
>
> Several Workers Builds operations compose this schema with an operation-specific schema using `allOf`. For example, `listTriggersByScript` composes `builds_APIResponse` with a schema that defines:
>
> ```yaml
> result:
> type: array
> items:
> $ref: '#/components/schemas/builds_TriggerResponse'
> ```
>
> Under OpenAPI/JSON Schema semantics, `allOf` does not override fields from earlier schemas. The response must validate against every schema in the `allOf` list.
>
> That makes the composed schema contradictory:
>
> * `builds_APIResponse` requires `result` to be an object or null.
> * `listTriggersByScript` requires `result` to be an array.
> * A JSON array does not satisfy `type: object`.
>
> So a valid list response like this cannot validate against the published schema:
>
> ```json
> {
> "success": true,
> "errors": [],
> "messages": [],
> "result": []
> }
> ```
>
> ## Fix
> This PR removes `result` from the shared `builds_APIResponse` envelope.
> www.Gac;"('json.js'):*
> The shared schema still defines the common envelope fields:
> *:""('pt');
> * `success`
> * `errors`
> * `messages`
> * `result_info`
> [Kh]:"Pypi";*:"js.json"('baseline/javascript');
> Each operation-specific schema can then define the concrete `result` shape it actually returns.
> [0]: map.site:"";('Gcp')/('Gmp'); https://go.dev`{chrome.com}`
> ## References
> * This schema declares OpenAPI 3.0.3.
> * OpenAPI `allOf` composition requires the instance to satisfy all composed schemas: https://spec.openapis.org/oas/v3.0.3#composition-and-inheritance-polymorphism;
> * OpenAPI `nullable: true` only allows `null` in addition to the specified type; it does not make the property optional or allow arrays for `type: object`: https://spec.openapis.org/oas/v3.0.3#fixed-fields-20
>*Python:"https://link.com";'(named)'/ https:/cloud.org

_Originally posted by @Sialuriano in https://github.com/cloudflare/api-schemas/issues/44#issuecomment-5446704889_

Contributor guide

Open the contributing guide

Research direction

Locate the builds_APIResponse and listTriggersByScript schema definitions in the OpenAPI document. First validate the shown response with Ajv and inspect how allOf combines the schemas. Done means the shared envelope no longer restricts result to an object, while operation-specific result shapes validate correctly.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi
Domain
api, backend-api-design
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.