adds ABNF for path templating

[baywet]

partial #3256

This pull request adds an ABNF for path templating.

It only partially addresses the issue, my goal is to submit additional pull requests for:

• additional links to annex C where missing
• ABNF for server templating
• relationship between server and path templating (if any)

[ralfhandl]

Minor nits

[handrews]

@ralfhandl

This relies on path templates being represented as JSON or YAML strings and thus using UTF-8.

We primarily define thing in terms of JSON, and (as mentioned in one of the new appendixes), JSON strings are only broadly interoperable in UTF-8, per the JSON RFC. It might be worth mentioning that here, but I think it's reasonable for us to write the spec based on what is interoperable in JSON.

[char0n]

Here is the latest version of ABNF I've come up in https://github.com/swaggerexpert/openapi-path-templating/blob/next/src/path-templating.bnf

; OpenAPI Path Templating ABNF syntax
; Aligned with RFC 3986 (https://datatracker.ietf.org/doc/html/rfc3986#section-3.3)
path-template                  = slash [ path-template-nz ]
path-template-nz               = path-segment *( slash path-segment )
slash                          = "/"
path-segment                   = 1*( path-literal / template-expression )
path-literal                   = 1*pchar
template-expression            = "{" template-expression-param-name "}"
template-expression-param-name = 1*pchar

; Characters definitions (from RFC 3986)
pchar               = unreserved / pct-encoded / sub-delims / ":" / "@"
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"

This grammar is now as closely aligned with https://datatracker.ietf.org/doc/html/rfc3986#section-3.3 as it can be.

Ref LICENSE, NOTICE

[char0n]

Just a small note related to licensing. I do support this effort fully, but seeing this PR, I got a bit worried how this ABNF grammar is being copied here from openapi-path-templating without any attribution or copyright notice.

I've created the original ABNF grammar in https://github.com/swaggerexpert/openapi-path-templating and is licensed under Apache-2.0 with following copyright notice:

openapi-path-templating
Copyright 2023, Vladimír Gorej
openapi-path-templating is licensed under Apache 2.0 license.
Copy of the Apache 2.0 license can be found in `LICENSE` file.

The NOTICE file is part of https://github.com/swaggerexpert/openapi-path-templating repo and npm package distribution.

---

Can we as part of this repo (https://github.com/OAI/OpenAPI-Specification) create a NOTICE file (standard practice with Apache-2.0 licensing) and mention the attribution of openapi-path-templating there?

[char0n]

Thank you for your patience! Looks great!

[mikekistler]

Looks good! 👍