OAI / OAI/OpenAPI-Specification

Runtime expression `name` rule inconsistent with path template grammar

Aperta
#5,285 10 commenti 1 reazione 0 assegnatari Vedi su GitHub

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

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. 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

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.