cloudflare / cloudflare/api-schemas

Workers Versions errors and messages require arrays in OpenAPI but are null in API responses

Open Beginner friendly
#47 1 comment 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 Workers Versions responses requires `errors` and `messages` to be arrays, but live Cloudflare API responses can return both fields as `null`.

Schema paths:

`#/components/schemas/workers_api-response-common/properties/errors`

`#/components/schemas/workers_api-response-common/properties/messages`

Both properties reference:

`#/components/schemas/workers_messages`

Endpoint confirmed:

`GET /accounts/{account_id}/workers/workers/{worker_id}/versions`

Schema repro:

```sh
curl -fsSL https://raw.githubusercontent.com/cloudflare/api-schemas/main/openapi.json \
| jq '{
errors: .components.schemas["workers_api-response-common"].properties.errors,
messages: .components.schemas["workers_api-response-common"].properties.messages,
workers_messages_type: .components.schemas.workers_messages.type
}'
```

Actual schema output:

```json
{
"errors": {
"$ref": "#/components/schemas/workers_messages"
},
"messages": {
"$ref": "#/components/schemas/workers_messages"
},
"workers_messages_type": "array"
}
```

Then call the Workers Versions endpoint:

```sh
curl -fsS \
"https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/workers/workers/$CLOUDFLARE_WORKER_ID/versions?per_page=1&page=1" \
-H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
| jq '{success, errors, messages}'
```

Observed live response shape:

```json
{
"success": true,
"errors": null,
"messages": null
}
```

Expected one of:

- successful API responses use empty arrays for `errors` and `messages`, or
- the OpenAPI response schema permits `null` for those fields.

Impact:

Strict clients generated from `cloudflare/api-schemas` reject otherwise successful Workers Versions responses. In our case, an Ajv validator generated from the schema rejected both fields because `null` does not satisfy `type: array`.

Contributor guide

Open the contributing guide

Research direction

Inspect the workers_api-response-common and workers_messages schemas in openapi.json, then run the jq repro and compare it with the documented Workers Versions response. Confirm the intended contract for null errors and messages, update the schema or response expectation accordingly, and verify that strict validation accepts a successful response.

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
64/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.