Fix Workers Builds response envelope schema

[nicu-chiciuc]

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

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:

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:

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:

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": []
}

Fix

This PR removes result from the shared builds_APIResponse envelope.

The shared schema still defines the common envelope fields:

• success
• errors
• messages
• result_info

Each operation-specific schema can then define the concrete result shape it actually returns.

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

[alexminza]

@kristianfreeman @jacobbednarz @musa-cf @tamas-jozsa why not enable Issues or at least Discussions for this repo on GitHub to allow sharing issues regarding the Cloudflare API?

[ssicard]

Thanks for the feedback @alexminza , we've enabled Issues.

Additionally, thanks for reporting this issue @nicu-chiciuc. I've created an internal ticket for this issue for investigation.

[nicu-chiciuc]

@ssicard, sorry to tag you again, but I've already submitted the 5th issue yesterday #48

It seems these are not small bugs but that this is a broader problem in the schema generation or validation process.

I have to catch these inconsistencies, then patch the official schemas and maintain provider-specific regression tests for things that are not part of my system.

I’m surprised this has not come up more often, since I assume other users also consume the OpenAPI schema.

Has anyone had a chance to look at the internal ticket you mentioned, and do you have any idea when the broader problem might be investigated?