cloudflare / cloudflare/api-schemas

Workers Builds build_outcome is non-nullable in OpenAPI but null while running

Open Beginner friendly
#48 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.