OAI / OAI/OpenAPI-Specification

Components fields name too restrictive?

Open
#1,387 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

clarification examples
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.