OpenAPI: some scalar fields have the wrong type in openapi_v3.yaml (e.g. milestone.group_id)
Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.
Summary
Distinct from the array under-typing (#604895): some scalar fields in doc/api/openapi/openapi_v3.yaml are typed as the wrong primitive, so strict typed clients fail to decode. Spec-accuracy defect — the API value is correct, the schema type is wrong.
Evidence
APIEntitiesMilestone.group_id is typed string but the API returns a number, producing typeMismatch String … found number instead when decoding a merge request that carries a milestone (GET /projects/278964/merge_requests/1).
Where it originates
The entity exposure (lib/api/entities/**.rb) documents a type that doesn't match the returned value. Same mechanism as #592838 (expose without an accurate documentation: { type: … } hint defaults to string) — that issue covers the boolean flavour; this one covers numeric fields like group_id.
Suggested fix
Correct the mistyped scalar (group_id → integer) at the entity exposure, and audit other numeric-vs-string fields for the same mismatch. group_id is the confirmed case; there are likely more. Documentation-only change.
Verification
A conformance check that validates real/recorded responses against the generated openapi_v3.yaml would catch this class of drift. The existing match_response_schema request-spec helpers use JSON schemas maintained separately from the OpenAPI spec, which is why these mismatches go unnoticed. (A downstream strict typed client that detects and retypes these on the fly can supply further instances on request.)
Related
- #604895 — array responses/fields typed as single objects: the other response-shape defect, found in the same strict-client decode run.
- #592838 — boolean flavour of the same root cause (missing/inaccurate
documentation:type hints). - #519959, #591007 (closed) — context: OpenAPI v3 tooling and spec validation. These mistypes are valid OpenAPI, so validation alone won't catch them.