cloudflare / cloudflare/api-schemas

Workers Builds metadata response schema disagrees with live API

Open Beginner friendly
#46 3 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_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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.