dns-records_dns-record-response requires data, but A/AAAA/CNAME/MX/NS/OPENPGPKEY/PTR/TXT records define no data property

[gilesw]

dns-records_dns-record-response marks data as required, but 8 of the record types it is composed from define no data property. As a result the schema is internally inconsistent: under the spec as written, an A, AAAA, CNAME, MX, NS, OPENPGPKEY, PTR or TXT record response is invalid.

Schema path:

#/components/schemas/dns-records_dns-record-response/required

It is used by dns-records_dns_response_single, dns-records_dns_response_collection, dns-records_dns-response-batch-object and dns-records_dns-response-review-scan-object, i.e. the DNS record get, list, create, update, patch and batch responses.

Repro:

curl -fsSL https://raw.githubusercontent.com/cloudflare/api-schemas/main/openapi.json \
  | jq -c '.components.schemas["dns-records_dns-record-response"].required'

["name","type","content","data","proxied","ttl","settings","comment","tags"]

The record-type branches reachable through dns-records_dns-record-without-data do not declare data:

curl -fsSL https://raw.githubusercontent.com/cloudflare/api-schemas/main/openapi.json \
  | jq -c '.components.schemas as $s | [ $s["dns-records_dns-record-without-data"].oneOf[]["$ref"] | split("/")[-1] | . as $n | { ($n): ([ $s[$n].allOf[] | (if has("$ref") then $s[.["$ref"] | split("/")[-1]] else . end) | (.properties // {}) | has("data") ] | any) } ] | add'

{"dns-records_ARecord":false,"dns-records_AAAARecord":false,"dns-records_CNAMERecord":false,"dns-records_MXRecord":false,"dns-records_NSRecord":false,"dns-records_OPENPGPKEYRecord":false,"dns-records_PTRRecord":false,"dns-records_TXTRecord":false}

Impact: code generators that honour required generate a record type where data is mandatory for every record, so decoding an A or MX record fails with missing field "data". I hit this generating a Rust client with openapi-to-rust and had to override the field by hand.

Suggested fix: drop data from the response-level required list. The with-data branches (CAA, SRV, HTTPS, …) can require it on their own.

Related question: comment, settings and tags are also required at the response level, while dns-records_dns-record-shared-fields leaves them optional and dns-records_comment is a non-nullable string. If the API can omit these fields, or return "comment": null for records without a comment, they should be optional or nullable in the response schema as well. I haven't checked the live API for this, so I'm only flagging it.