OAI / OAI/OpenAPI-Specification
Extensible enumerations (growable lists)
Nobody has claimed this yet.
- Dominant language
- Markdown
- Stars
- 31.2k
- Forks
- 9.2k
- Avg merge
- 6h 37m
- Merged PRs (30d)
- 27
Description
Hey all,
I did some searching in the OAI repo, and it didn't jump out at me as an existing feature request.
The issues with enum being "non-growable" without making a major semver change for an API have been talked about in several places. Zalando came up with nice framework within their API guidelines to handle this, which would be incredibly useful to upstream into the specification itself
https://zalando.github.io/restful-api-guidelines/#112
Should: Used Open-Ended List of Values (x-extensible-enum) Instead of Enumerations [112]
Enumerations are per definition closed sets of values, that are assumed to be complete and not intended for extension. This closed principle of enumerations imposes compatibility issues when an enumeration must be extended. To avoid these issues, we strongly recommend to use an open-ended list of values instead of an enumeration unless:the API has full control of the enumeration values, i.e. the list of values does not depend on any external tool or interface, and
the list of value is complete with respect to any thinkable and unthinkable future feature.
To specify an open-ended list of values use the marker x-extensible-enum as follows:
deliver_methods:
type: string
x-extensible-enum:
- parcel
- letter
- email
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
Start with the issue proposal and the linked Zalando API guidelines, since no implementation file or test is named. Review the OpenAPI specification structure to determine where extensible enumerations would be defined. Done requires an agreed specification change describing the marker and its behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi
- Domain
- api
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100