OAI / OAI/OpenAPI-Specification
Runtime expression `name` rule inconsistent with path template grammar
Dieses Issue hat noch niemand übernommen.
- Vorherrschende Sprache
- Markdown
- Sterne
- 31.2k
- Forks
- 9.2k
- Ø Merge
- 6 Std. 37 Min.
- Gemergte PRs (30 T.)
- 27
Beschreibung
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.
Beitragsleitfaden
Erste Schritte
- Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
- Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
- Forke das Repository und arbeite in einem Branch.
- Öffne einen Pull Request, der die Issue-Nummer nennt.
Rechercherichtung
Lies die ABNF-Regeln des Runtime-Ausdrucks für name und token zusammen mit der Pfadvorlagengrammatik von OpenAPI 3.2. Kläre, ob leere Query-Namen vorgesehen sind, bevor entschieden wird, ob name ein Zeichen erfordern sollte; die Aufgabe ist abgeschlossen, wenn die Grammatik und der umgebende Spezifikationstext die Entscheidung konsistent dokumentieren.
Vom Indexierungsmodell aus dem Issue-Text verfasst.
Bewertung
- Tech-Stack
- markdown
- Bereich
- backend-api-design, documentation
- Issue-Typ
- Dokumentation
- Schwierigkeit
- 3/5
- Geschätzter Aufwand
- 1-2 Tage
- Aktivitätsstatus
- Ruhig
- Klarheit
- Größtenteils klar
- Anfängerfreundlichkeit
- 45/100