OAI / OAI/OpenAPI-Specification

Runtime expression `name` rule inconsistent with path template grammar

Open
#5,285 10 comments 1 reaction 0 assignees View on GitHub

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

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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.