swagger-api / swagger-api/swagger.io-docs
OAS 3 : allOf specification missing ?
Nobody has claimed this yet.
- Dominant language
- Astro
- Stars
- 1.6k
- Forks
- 407
- Avg merge
- 2m
- Merged PRs (30d)
- 2
Description
Hello Everyone,
I was wondering why the allOf at array level was not documented, because it is working perfectly :
(in the screenshot the swagger has been simplified for clarity purposes)


But because of the spec mentionned at https://spec.openapis.org/oas/latest.html :
4.8.24.2.1 Composition and Inheritance (Polymorphism) §
The OpenAPI Specification allows combining and extending model definitions using the allOf property of JSON Schema, in effect offering model composition. allOf takes an array of object definitions that are validated independently but together compose a single object.
While composition offers model extensibility, it does not imply a hierarchy between the models. To support polymorphism, the OpenAPI Specification adds the discriminator field. When used, the discriminator will be the name of the property that decides which schema definition validates the structure of the model. As such, the discriminator field MUST be a required field. There are two ways to define the value of a discriminator for an inheriting instance.
My company is using those specs to validate swaggers, and because of that my AllOf is refused.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Compare the current swagger.io documentation with the OpenAPI Specification section on Composition and Inheritance linked in the issue, using the reported array-level allOf example as context. Confirm whether this valid usage is omitted, and consider the work done when the documentation accurately explains the supported form and its validation implications.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100