Formally define 3.x URL templating behavior

[handrews]

As noted in Slack discussions, there is no formal specification for where variables can appear in server URL templates and path templates. There does not seem to be any reason to place restrictions on it.

Ideally, we could leverage the ABNF of RFC 6570 URI Templates even though OAS 3.x templating is not the same as RFC 6570 in general. (@darrelmiller @webron @MikeRalphson any concerns here?)

[handrews]

Issue #2119 brings up a lot of points relevant to this.

[char0n]

@handrews I created a implementation with formal ANBF grammar in https://github.com/char0n/openapi-path-templating.

I did a couple of assumption, because of the fact that the templating is not defined very precisely. Hope it helps a bit.

There does not seem to be any reason to place restrictions on it.

IMHO the restriction would be to now allow template expressions in URL query (searchParams) and URL fragment

[handrews]

@char0n thank you! I don't know if we're going to get to this in the current patch releases or not (I'm unassigning it for onw as I have too many things in my backlog), but this will help when we do get there!

[handrews]

@char0n I took a look at your ABNF- it looks like it restricts path template variables to whole segments. This issue got filed because in a discussion with TSC folks on slack, it was decided that template variables are not restricted to whole segments. You can have a template like /foo{bar}/whatever. I don't know how many API descriptions actually do that, but I figured you might want to know since the initial comment in this issue was not sufficiently clear.

[char0n]

@handrews I've created implementation with formal ABNF grammar for Server URL Templating in https://github.com/char0n/openapi-server-url-templating.

It's distinct from https://github.com/char0n/openapi-path-templating, as the Server URL Templating is based on RFC 6570, but Path Templating is more based on RFC 3986.

[char0n]

@char0n I took a look at your ABNF- it looks like it restricts path template variables to whole segments. This issue got filed because in a discussion with TSC folks on slack, it was decided that template variables are not restricted to whole segments. You can have a template like /foo{bar}/whatever. I don't know how many API descriptions actually do that, but I figured you might want to know since the initial comment in this issue was not sufficiently clear.

The grammar is not restricted to the whole segments:

path-segment                   = 1*( path-literal / template-expression )

path-segment is defined as non-terminal rule containing one or more path-literal or template-expression.

This path template /foo{bar}/whatever' is parsed into following AST:

[
  [ 'path-template', '/foo{bar}/whatever' ],
  [ 'path', '/foo{bar}/whatever' ],
  [ 'slash', '/' ],
  [ 'path-literal', 'foo' ],
  [ 'template-expression', '{bar}' ],
  [ 'template-expression-param-name', 'bar' ],
  [ 'slash', '/' ],
  [ 'path-literal', 'whatever' ]
]

NOTE: there is a test that guarantee this works as expected in https://github.com/char0n/openapi-path-templating/blob/bea2682e889a6bc06da95596b303dcc77304402f/test/parse.js#L45

[char0n]

@handrews,

There is one un-clarity related to template-expression-param-name rule from openapi-path-templating. OpenAPI spec doesn't technically constrain Parameter Object.name fixed field in any way. It just says it's a string. This means that people can use "parameter name" as a value.

This also means that the path template will need to be defined as /{parameter name}

It's just another example how OpenAPI Path Templating differs from RFC 6570.

---

@handrews taking into account the above, template-expression-param-name should be less constrained and in theory should allow any non empty string value. What do you think?