OAI / OAI/OpenAPI-Specification
Runtime expression `name` rule inconsistent with path template grammar
Nobody has claimed this yet.
- Dominant language
- Markdown
- Stars
- 31.2k
- Forks
- 9.2k
- Avg merge
- 6h 37m
- Merged PRs (30d)
- 27
Description
The runtime expression ABNF grammar defines:
name = *( char )
token = 1*tchar
The * (zero or more) quantifier on name means expressions like $request.query. and $request.path. with empty names are syntactically valid per the grammar.
The OpenAPI spec states that the Parameter Object's name field is REQUIRED:
REQUIRED. The name of the parameter. Parameter names are case-sensitive.
A required field with an empty string value is arguably not meaningful, though the spec doesn't explicitly say "non-empty".
For path parameters specifically, this is inconsistent with the path template grammar introduced in OpenAPI 3.2.0:
template-expression-param-name = 1*( %x00-7A / %x7C / %x7E-10FFFF )
The 1* quantifier requires at least one character for path parameter names. So {userId} is valid but {} is not. Yet the runtime expression $request.path. (empty name) is accepted by the grammar.
For query parameters, the situation is less clear — HTTP technically allows empty query parameter keys (?=value), though this is extremely uncommon.
For consistency with the path template grammar and the token = 1*tchar rule (which already requires at least one character for headers), consider changing:
name = *( char )
to:
name = 1*( char )
This would require at least one character for query and path parameter names, aligning the runtime expression grammar with the path template grammar.
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
Read the runtime expression ABNF rules for name and token alongside the OpenAPI 3.2 path template grammar. Resolve whether empty query names are intended before deciding whether name should require one character; done means the grammar and surrounding specification text consistently document the decision.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown
- Domain
- backend-api-design, documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100