cloudflare / cloudflare/api-schemas
Workers Builds metadata response schema disagrees with live API
- Dominant language
- No language data
- Stars
- 188
- Forks
- 69
- PR merge metrics
- No merged PRs in 30d
Description
The OpenAPI schema for `builds_BuildTriggerMetadataResponse` disagrees with live responses from:
`GET /accounts/{account_id}/builds/workers/{external_script_id}/builds`
I verified this against current schema commit [`c773f5d46de208d2769eed40a465586431bad5e3`](https://github.com/cloudflare/api-schemas/commit/c773f5d46de208d2769eed40a465586431bad5e3).
There are two independent mismatches in `builds_BuildTriggerMetadataResponse`.
## 1. `build_trigger_source`
Response property path:
`#/components/schemas/builds_BuildTriggerMetadataResponse/properties/build_trigger_source`
Referenced component:
`#/components/schemas/builds_BuildTriggerSource`
The published enum is:
```json
[
"push",
"pull_request",
"manual",
"api"
]
```
Live build-list responses return `"push_event"` for builds triggered by a Git push. `"push_event"` is not accepted by the published enum.
## 2. `environment_variables`
Schema path:
`#/components/schemas/builds_BuildTriggerMetadataResponse/properties/environment_variables`
The published schema declares a string map:
```json
{
"type": "object",
"additionalProperties": {
"type": "string"
}
}
```
Live build-list responses instead return an object per environment variable with these fields:
```json
{
"created_on": "...",
"is_secret": true,
"value": null
}
```
That live shape already has a matching component in the published schema:
`#/components/schemas/builds_EnvironmentVariablesResponse`
## Reproduction
Inspect the exact published definitions:
```sh
SCHEMA_COMMIT=c773f5d46de208d2769eed40a465586431bad5e3
curl -fsSL \
"https://raw.githubusercontent.com/cloudflare/api-schemas/$SCHEMA_COMMIT/openapi.json" \
| jq '{
build_trigger_source: .components.schemas.builds_BuildTriggerSource,
environment_variables: .components.schemas.builds_BuildTriggerMetadataResponse.properties.environment_variables,
existing_response_shape: .components.schemas.builds_EnvironmentVariablesResponse
}'
```
Then inspect only the relevant, non-secret shapes from a live build-list response:
```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 '{
build_trigger_sources: (
[.result[] | .build_trigger_metadata.build_trigger_source] | unique
),
environment_variable_value_types: (
[
.result[]
| (.build_trigger_metadata.environment_variables // {})
| to_entries[]
| .value
| type
]
| unique
)
}'
```
Observed output across live Workers:
```json
{
"build_trigger_sources": [
"manual",
"push_event"
],
"environment_variable_value_types": [
"object"
]
}
```
## Independent validation
I validated 600 live `builds_BuildResponse` objects from three Workers directly with Ajv against the exact component at schema commit `c773f5d`:
- 599 of 600 objects were rejected.
- 588 errors were the `build_trigger_source` enum rejecting `push_event`.
- 679 errors were `environment_variables` values not being strings.
- There were no other validation errors.
I then changed only these two definitions in memory:
1. Allowed `push_event` in `builds_BuildTriggerSource`.
2. Pointed `builds_BuildTriggerMetadataResponse.environment_variables` to `builds_EnvironmentVariablesResponse`.
All 600 of 600 live build objects then validated successfully.
This validation targets individual `builds_BuildResponse` objects, so it is independent of the separate response-envelope contradiction reported in #44.
## Expected
- `builds_BuildTriggerSource` accepts the value emitted by the API for Git push events (`push_event`), or the API emits the documented `push` value.
- `builds_BuildTriggerMetadataResponse.environment_variables` uses the existing `builds_EnvironmentVariablesResponse` shape.
## Impact
Strict clients and runtime validators generated from `cloudflare/api-schemas` reject otherwise successful Workers Builds history responses. Because the endpoint returns an array, one incompatible build object causes the entire response page to be rejected.
Contributor guide
Research direction
Start with openapi.json and inspect builds_BuildTriggerSource plus the environment_variables property of builds_BuildTriggerMetadataResponse, alongside builds_EnvironmentVariablesResponse. Run the issue's curl/jq reproduction and compare the published definitions with live build-list responses. Done means the relevant live objects validate successfully against the corrected schema definitions.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- json
- Domain
- api
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 76/100