OAI / OAI/OpenAPI-Specification
Components fields name too restrictive?
Nobody has claimed this yet.
- Dominant language
- Markdown
- Stars
- 31.2k
- Forks
- 9.2k
- Avg merge
- 6h 37m
- Merged PRs (30d)
- 27
Description
Components fields name currently has this regex as restrictions: ^[a-zA-Z0-9\.\-_]+$
This was mainly discussed and agreed on in #634.
I found this restriction a little too restrictive. I'd imagine that for the Schemas part of the component, most people will use class names as field names. Allowing the period (.) is good because that allows you to add namespace to class name Namespace.ClassName.
However, quite a number of languages have generics and APIs can have request body that are of type implementing generics. The current allowed characters make it very difficult to represent class name that is derived from generic type. The most intuitive (I think) way to represent generic class name as string is to use some kind of brackets/parentheses Namespace.GenericClassName(AnotherClassName). Of course, one can bypass this by using the allowed underscore or hyphen instead, but that just looks plain ugly.
Should we allow parentheses and/or brackets?
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 component field-name regex shown in the issue and read the prior discussion in #634. Determine whether parentheses or brackets should be allowed for generic type names, then update the specification and any related validation guidance once the syntax decision is settled.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi
- Domain
- api, documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100