cloudflare / cloudflare/api-schemas
Workers Builds build_outcome is non-nullable in OpenAPI but null while running
- Dominant language
- No language data
- Stars
- 188
- Forks
- 69
- PR merge metrics
- No merged PRs in 30d
Description
The OpenAPI schema for `builds_BuildOutcome` permits only terminal string values. The live API returns `builds_BuildResponse.build_outcome` as `null` while `builds_BuildResponse.status` is `running`.
I verified both points against the current schema at commit [`791663f57e4312d14bfef614efef61dea72a12a9`](https://github.com/cloudflare/api-schemas/commit/791663f57e4312d14bfef614efef61dea72a12a9).
Schema path:
`#/components/schemas/builds_BuildOutcome`
Response property:
`#/components/schemas/builds_BuildResponse/properties/build_outcome`
## Published schema
```json
{
"type": "string",
"example": "success",
"enum": [
"success",
"fail",
"skipped",
"cancelled",
"terminated"
]
}
```
## Reproduction
Inspect the exact published definitions:
```sh
SCHEMA_COMMIT=791663f57e4312d14bfef614efef61dea72a12a9
curl -fsSL \
"https://raw.githubusercontent.com/cloudflare/api-schemas/$SCHEMA_COMMIT/openapi.json" \
| jq '{
build_outcome: .components.schemas.builds_BuildOutcome,
response_property: .components.schemas.builds_BuildResponse.properties.build_outcome
}'
```
Start a Worker build. While `builds_BuildResponse.status` is `running`, call the build-list endpoint:
```sh
curl -fsS \
"https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/builds/workers/$CLOUDFLARE_WORKER_TAG/builds?page=1&per_page=100" \
-H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
| jq '[
.result[]
| select(.status == "running")
| {
status,
build_outcome,
stopped_on
}
]'
```
Observed live response shape:
```json
[
{
"status": "running",
"build_outcome": null,
"stopped_on": null
}
]
```
This output includes only lifecycle fields. It does not expose account identifiers, Worker identifiers, build identifiers, environment variables, or credentials.
## Validation
A strict Ajv validator generated from the published schema rejected the running `builds_BuildResponse` at:
```text
/result/0/build_outcome
```
The validation errors were:
```text
must be string
must be equal to one of the allowed values
```
After I changed only `builds_BuildOutcome` to permit `null`, the observed running response passed this part of validation.
This mismatch is independent of #46. That issue covers `build_trigger_source` and `environment_variables` in `builds_BuildTriggerMetadataResponse`. This report covers the top-level lifecycle field `builds_BuildResponse.build_outcome`.
## Expected
One of these behaviors:
- `builds_BuildOutcome` permits `null` until the build has a terminal outcome.
- The API omits `build_outcome` until a terminal string is available.
## Impact
Strict clients and runtime validators generated from `cloudflare/api-schemas` reject the full build-list response when it contains a `builds_BuildResponse` with `status: "running"`. In our case, this made the current build appear unavailable until it finished, although the API correctly reported its status as `running`.
Contributor guide
Research direction
Start with openapi.json and inspect components.schemas.builds_BuildOutcome plus builds_BuildResponse.properties.build_outcome. Reproduce the running-build response with the supplied curl and jq commands, then update the schema behavior for a null or absent outcome and add or adjust validation coverage. Done means a running build response passes strict validation while terminal outcomes remain constrained.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi
- Domain
- api
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 72/100