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]

The only explicit restriction we state is that

Each template expression in the path MUST correspond to a path parameter

and there are no restrictions on path parameter names.

The only implicit restriction is that the } cannot be used in a template expression because we don't define an escaping mechanism for it.

[baywet]

so you'd extend what's in there in essence? I double checked RFC5234 and there does not appear to be any way so simply say "anything but this character", and I think it's on purpose.

What do you think is missing? %[]^"'<>? ?

[ralfhandl]

Trick question: which ABNF rule is equivalent to regexp ^[^}]+$ 😎

[baywet]

that's effectively what I was looking for, couldn't find an equivalent, but maybe I missed something?

[ralfhandl]

My ABNF knowledge reaches its limits with this question 😞

[ralfhandl]

The most generous rule would be

Suggested change

	template-expression-param-name = 1*( unreserved / pct-encoded / sub-delims / ":" / "@" )
	template-expression-param-name = 1*( %x00-7C / %x7E-10FFFF ) ; every Unicode character except "}"

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

[baywet]

@ralfhandl should we also at least exclude { ? it'd probably make parser's lives much easier.

[ralfhandl]

@handrews?

[handrews]

@ralfhandl @baywet I'd consider /foo/{bar{baz}/stuff to be an error, because it's ambiguous as to whether the template name here is bar{baz or just baz. We don't define a precedence or parse order, so there's no way to resolve this. Therefore I think we can exclude it. If we want to put this into 3.1.2 we can finesse it by saying that the behavior of any template that does not match the ABNF is implementation-defined. That's valid to do when there's ambiguity. The same logic would apply to apparently-nested names, e.g. /foo/{bar{baz}abc}/

But for things like using a space in a template name... there's nothing that forbids it and nothing that makes its parsing exceptionally difficult, much less ambiguous. In YAML you can even write:

/{foo bar}:
  parameters:
  - in: path
    name: foo bar

and it parses just fine:

>>> yaml.safe_load("""
... /{foo bar}:
...   parameters:
...   - in: path
...     name: foo bar
... """)
{'/{foo bar}': {'parameters': [{'in': 'path', 'name': 'foo bar'}]}}

For the control characters, you could technically use the same argument as for the space character, but I think there's a reasonable expectations that control characters are always a special case, and are implicitly excluded if they are not explicitly included. I am completely making that rule up, but I suspect it won't bother people. On the other hand, I would not be at all surprised if someone put a space in a template variable name. For... reasons.

[baywet]

Thanks for all this additional information!

I think we're reaching a consensus to this

%x00-79 / %x7C / %x7E-10FFFF ; every UTF8 character except { and }

Thoughts?

[ralfhandl]

Minor nits

[ralfhandl]

The most generous rule would be

Suggested change

	template-expression-param-name = 1*( unreserved / pct-encoded / sub-delims / ":" / "@" )
	template-expression-param-name = 1*( %x00-7C / %x7E-10FFFF ) ; every Unicode character except "}"

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

[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.