OAI / OAI/OpenAPI-Specification
Runtime expression `name` rule inconsistent with path template grammar
Nessuno ha ancora preso questa issue.
- Lingua principale
- Markdown
- Stelle
- 31.2k
- Fork
- 9.2k
- Merge medio
- 6h 37m
- PR unite (30g)
- 27
Descrizione
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.
Guida per i contributori
Apri la guida per i contributori
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Direzione di ricerca
Leggi le regole ABNF dell’espressione runtime per name e token insieme alla grammatica dei template dei percorsi di OpenAPI 3.2. Determina se i nomi di query vuoti sono previsti prima di decidere se name debba richiedere un carattere; il lavoro è completato quando la grammatica e il testo circostante della specifica documentano coerentemente la decisione.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- markdown
- Ambito
- backend-api-design, documentation
- Tipo di issue
- Documentazione
- Difficoltà
- 3/5
- Tempo stimato
- 1-2 giorni
- Stato di attività
- Tranquilla
- Chiarezza
- Abbastanza chiara
- Idoneità per principianti
- 45/100