From 681dab76679285d28ca56dc63cdeb072de390fc3 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Thu, 5 Dec 2024 15:56:03 -0500 Subject: [PATCH 01/12] 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 02/12] 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 03/12] 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 04/12] 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 "}" From fc576083e3b9a40fa7d2066d66ce7f26c1ba8983 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Mon, 16 Dec 2024 12:51:09 +0100 Subject: [PATCH 05/12] Apparent consensus --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index c7f02beb48..04e0ac0d25 100644 --- a/src/oas.md +++ b/src/oas.md @@ -53,7 +53,7 @@ path-segment = 1*( path-literal / template-expression ) 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 / ":" / "@" ) +template-expression-param-name = 1*( %x00-79 / %x7C / %x7E-10FFFF ) ; every UTF8 character except { and } ; Characters definitions (from RFC 3986) unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" From 1da9fbbbce16ea22da73951fdefdd1d32c447664 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Mon, 16 Dec 2024 08:07:29 -0500 Subject: [PATCH 06/12] chore: adds pchar from RFC3986 Signed-off-by: Vincent Biret --- src/oas.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 04e0ac0d25..8941004f75 100644 --- a/src/oas.md +++ b/src/oas.md @@ -51,11 +51,12 @@ The path templating expression is defined by the following [ABNF](https://tools. path-template = slash *( path-segment slash ) [ path-segment ] path-segment = 1*( path-literal / template-expression ) slash = "/" -path-literal = 1*( unreserved / pct-encoded / sub-delims / ":" / "@" ) +path-literal = 1*pchar template-expression = "{" template-expression-param-name "}" template-expression-param-name = 1*( %x00-79 / %x7C / %x7E-10FFFF ) ; every UTF8 character except { and } ; Characters definitions (from RFC 3986) +pchar = unreserved / pct-encoded / sub-delims / ":" / "@" unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" pct-encoded = "%" HEXDIG HEXDIG sub-delims = "!" / "$" / "&" / "'" / "(" / ")" From 566aee43c71a01b4b0845f21432f0063a608805a Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Mon, 16 Dec 2024 09:31:59 -0500 Subject: [PATCH 07/12] chore: makes slash terminal --- src/oas.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/oas.md b/src/oas.md index 8941004f75..36e1e147fd 100644 --- a/src/oas.md +++ b/src/oas.md @@ -48,9 +48,8 @@ The path templating expression is defined by the following [ABNF](https://tools. ```abnf ; OpenAPI Path Templating ABNF syntax -path-template = slash *( path-segment slash ) [ path-segment ] +path-template = "/" *( path-segment "/" ) [ path-segment ] path-segment = 1*( path-literal / template-expression ) -slash = "/" path-literal = 1*pchar template-expression = "{" template-expression-param-name "}" template-expression-param-name = 1*( %x00-79 / %x7C / %x7E-10FFFF ) ; every UTF8 character except { and } From 758f44bfcbc6da19d3ae5343744b5901abef85f5 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Mon, 16 Dec 2024 10:17:15 -0500 Subject: [PATCH 08/12] chore: updates wording MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Vladimír Gorej --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 36e1e147fd..c179368723 100644 --- a/src/oas.md +++ b/src/oas.md @@ -44,7 +44,7 @@ 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 +The path templating is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax ```abnf ; OpenAPI Path Templating ABNF syntax From e4caedca6906ee964690e8879a06eee7edc2fabc Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Tue, 17 Dec 2024 07:03:06 -0500 Subject: [PATCH 09/12] chore: moves RFC references outside of ABNF block for path templates Signed-off-by: Vincent Biret --- src/oas.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/oas.md b/src/oas.md index c179368723..94d983c302 100644 --- a/src/oas.md +++ b/src/oas.md @@ -47,14 +47,12 @@ The value for these path parameters MUST NOT contain any unescaped "generic synt The path templating is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax ```abnf -; OpenAPI Path Templating ABNF syntax path-template = "/" *( path-segment "/" ) [ path-segment ] path-segment = 1*( path-literal / template-expression ) path-literal = 1*pchar template-expression = "{" template-expression-param-name "}" template-expression-param-name = 1*( %x00-79 / %x7C / %x7E-10FFFF ) ; every UTF8 character except { and } -; Characters definitions (from RFC 3986) pchar = unreserved / pct-encoded / sub-delims / ":" / "@" unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" pct-encoded = "%" HEXDIG HEXDIG @@ -65,6 +63,8 @@ DIGIT = %x30-39 ; 0-9 HEXDIG = DIGIT / "A" / "B" / "C" / "D" / "E" / "F" ``` +Here, all characters definitions are taken from [RFC 3986](https://tools.ietf.org/html/rfc3986). The path-template is directly derived from [RFC 3986, section 3.3](https://datatracker.ietf.org/doc/html/rfc3986#section-3.3). + ### Media Types Media type definitions are spread across several resources. From 3063a8938aca11275053313c93748b86b0f15f82 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Tue, 17 Dec 2024 07:37:12 -0500 Subject: [PATCH 10/12] chore: adds missing quotes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Vladimír Gorej --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 94d983c302..671687f7a3 100644 --- a/src/oas.md +++ b/src/oas.md @@ -63,7 +63,7 @@ DIGIT = %x30-39 ; 0-9 HEXDIG = DIGIT / "A" / "B" / "C" / "D" / "E" / "F" ``` -Here, all characters definitions are taken from [RFC 3986](https://tools.ietf.org/html/rfc3986). The path-template is directly derived from [RFC 3986, section 3.3](https://datatracker.ietf.org/doc/html/rfc3986#section-3.3). +Here, all characters definitions are taken from [RFC 3986](https://tools.ietf.org/html/rfc3986). The `path-template` is directly derived from [RFC 3986, section 3.3](https://datatracker.ietf.org/doc/html/rfc3986#section-3.3). ### Media Types From a2873d805a7bc4f8350daa3bca0165f78202ba44 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Tue, 17 Dec 2024 07:43:43 -0500 Subject: [PATCH 11/12] chore: removes basic alpha digit hexdig definition Signed-off-by: Vincent Biret --- src/oas.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/src/oas.md b/src/oas.md index 94d983c302..4280480e57 100644 --- a/src/oas.md +++ b/src/oas.md @@ -58,9 +58,6 @@ 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" ``` Here, all characters definitions are taken from [RFC 3986](https://tools.ietf.org/html/rfc3986). The path-template is directly derived from [RFC 3986, section 3.3](https://datatracker.ietf.org/doc/html/rfc3986#section-3.3). From 72d93b893b49fc26ea6d3b9439090d9bb127a670 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Wed, 18 Dec 2024 07:40:32 -0500 Subject: [PATCH 12/12] chore: explicitly lists out which definitions come from another RFC Signed-off-by: Vincent Biret --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 943834275a..4106fbc320 100644 --- a/src/oas.md +++ b/src/oas.md @@ -60,7 +60,7 @@ sub-delims = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "=" ``` -Here, all characters definitions are taken from [RFC 3986](https://tools.ietf.org/html/rfc3986). The `path-template` is directly derived from [RFC 3986, section 3.3](https://datatracker.ietf.org/doc/html/rfc3986#section-3.3). +Here, `pchar`, `unreserved`, `pct-encoded` and `sub-delims` definitions are taken from [RFC 3986](https://tools.ietf.org/html/rfc3986). The `path-template` is directly derived from [RFC 3986, section 3.3](https://datatracker.ietf.org/doc/html/rfc3986#section-3.3). ### Media Types