> I couldn't figure out how to report an issue regarding this so I opened a PR.
- 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
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