From 681dab76679285d28ca56dc63cdeb072de390fc3 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Thu, 5 Dec 2024 15:56:03 -0500 Subject: [PATCH 1/4] docs: adds draft abnf for path templating --- src/oas.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/src/oas.md b/src/oas.md index a5d98bdd8b..9a9f2c5833 100644 --- a/src/oas.md +++ b/src/oas.md @@ -44,6 +44,34 @@ Each template expression in the path MUST correspond to a path parameter that is The value for these path parameters MUST NOT contain any unescaped "generic syntax" characters described by [RFC3986](https://tools.ietf.org/html/rfc3986#section-3): forward slashes (`/`), question marks (`?`), or hashes (`#`). +The path templating expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax + +```abnf +; OpenAPI Path Templating ABNF syntax +path-template = path [ query-marker query ] [ fragment-marker fragment ] +path = slash *( path-segment slash ) [ path-segment ] +path-segment = 1*( path-literal / template-expression ) +query = *( query-literal ) +query-literal = 1*( unreserved / pct-encoded / sub-delims / ":" / "@" / "/" / "?" / "&" / "=" ) +query-marker = "?" +fragment = *( fragment-literal ) +fragment-literal = 1*( unreserved / pct-encoded / sub-delims / ":" / "@" / "/" / "?" ) +fragment-marker = "#" +slash = "/" +path-literal = 1*( unreserved / pct-encoded / sub-delims / ":" / "@" ) +template-expression = "{" template-expression-param-name "}" +template-expression-param-name = 1*( unreserved / pct-encoded / sub-delims / ":" / "@" ) + +; Characters definitions (from RFC 3986) +unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" +pct-encoded = "%" HEXDIG HEXDIG +sub-delims = "!" / "$" / "&" / "'" / "(" / ")" + / "*" / "+" / "," / ";" / "=" +ALPHA = %x41-5A / %x61-7A ; A-Z / a-z +DIGIT = %x30-39 ; 0-9 +HEXDIG = DIGIT / "A" / "B" / "C" / "D" / "E" / "F" +``` + ### Media Types Media type definitions are spread across several resources. From 09f5c1ca91be240841295f1b31248e0cfa6b33ba Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Thu, 5 Dec 2024 16:04:34 -0500 Subject: [PATCH 2/4] fix: removes fragment part Signed-off-by: Vincent Biret --- src/oas.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/src/oas.md b/src/oas.md index 9a9f2c5833..3da1d828fa 100644 --- a/src/oas.md +++ b/src/oas.md @@ -48,15 +48,12 @@ The path templating expression is defined by the following [ABNF](https://tools. ```abnf ; OpenAPI Path Templating ABNF syntax -path-template = path [ query-marker query ] [ fragment-marker fragment ] +path-template = path [ query-marker query ] path = slash *( path-segment slash ) [ path-segment ] path-segment = 1*( path-literal / template-expression ) query = *( query-literal ) query-literal = 1*( unreserved / pct-encoded / sub-delims / ":" / "@" / "/" / "?" / "&" / "=" ) query-marker = "?" -fragment = *( fragment-literal ) -fragment-literal = 1*( unreserved / pct-encoded / sub-delims / ":" / "@" / "/" / "?" ) -fragment-marker = "#" slash = "/" path-literal = 1*( unreserved / pct-encoded / sub-delims / ":" / "@" ) template-expression = "{" template-expression-param-name "}" From fb136768a939723415b3637f8817ec06c3468a7c Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 6 Dec 2024 08:02:31 -0500 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Ralf Handl --- src/oas.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/oas.md b/src/oas.md index 3da1d828fa..6abaa6f8c4 100644 --- a/src/oas.md +++ b/src/oas.md @@ -52,7 +52,7 @@ path-template = path [ query-marker query ] path = slash *( path-segment slash ) [ path-segment ] path-segment = 1*( path-literal / template-expression ) query = *( query-literal ) -query-literal = 1*( unreserved / pct-encoded / sub-delims / ":" / "@" / "/" / "?" / "&" / "=" ) +query-literal = 1*( unreserved / pct-encoded / sub-delims / ":" / "@" / "/" / "?" ) query-marker = "?" slash = "/" path-literal = 1*( unreserved / pct-encoded / sub-delims / ":" / "@" ) @@ -65,7 +65,7 @@ pct-encoded = "%" HEXDIG HEXDIG sub-delims = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "=" ALPHA = %x41-5A / %x61-7A ; A-Z / a-z -DIGIT = %x30-39 ; 0-9 +DIGIT = %x30-39 ; 0-9 HEXDIG = DIGIT / "A" / "B" / "C" / "D" / "E" / "F" ``` From b6d642f13bfa5ffad5084987f10d5659b393a530 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 6 Dec 2024 08:20:40 -0500 Subject: [PATCH 4/4] fix: removes query parameter Co-authored-by: Ralf Handl --- src/oas.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/src/oas.md b/src/oas.md index 6abaa6f8c4..c7f02beb48 100644 --- a/src/oas.md +++ b/src/oas.md @@ -48,12 +48,8 @@ The path templating expression is defined by the following [ABNF](https://tools. ```abnf ; OpenAPI Path Templating ABNF syntax -path-template = path [ query-marker query ] -path = slash *( path-segment slash ) [ path-segment ] +path-template = slash *( path-segment slash ) [ path-segment ] path-segment = 1*( path-literal / template-expression ) -query = *( query-literal ) -query-literal = 1*( unreserved / pct-encoded / sub-delims / ":" / "@" / "/" / "?" ) -query-marker = "?" slash = "/" path-literal = 1*( unreserved / pct-encoded / sub-delims / ":" / "@" ) template-expression = "{" template-expression-param-name "}"