improve wording for servers object and url

[karenetheridge]

I just implemented request matching with server urls, and found a few places where the spec could be made a little clearer.

• schema changes are included in this pull request
• schema changes are needed for this pull request but not done yet
• no schema changes are needed for this pull request

[handrews]

Super-nitpick: I think template variable substitution has to take place before relative URI-reference resolution, so perhaps reverse these?

Suggested change

| <a name="paths-path"></a>/{path} | [Path Item Object](#path-item-object) | A relative path to an individual endpoint. The field name MUST begin with a forward slash (`/`). The path is **appended** (no relative URL resolution) to the resolved and template variable-substituted URL from the [Server Object](#server-object)'s `url` field in order to construct the full URL. [Path templating](#path-templating) is allowed. When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical. In case of ambiguous matching, it's up to the tooling to decide which one to use. |

| <a name="paths-path"></a>/{path} | [Path Item Object](#path-item-object) | A relative path to an individual endpoint. The field name MUST begin with a forward slash (`/`). The path is **appended** (no relative URL resolution) to the template variable-substituted and resolved URL from the [Server Object](#server-object)'s `url` field in order to construct the full URL. [Path templating](#path-templating) is allowed. When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical. In case of ambiguous matching, it's up to the tooling to decide which one to use. |

[karenetheridge]

I think template variable substitution has to take place before relative URI-reference resolution

Why?

And, how? If the URI is relative (it hasn't been resolved to an absolute URI yet) then trying to match it against an absolute URI from the HTTP request will fail. You need the whole thing to match against.

[handrews]

Because it's possible to write a templatized URI reference that will resolve differently depending on how the template is filled out. For example, I don't believe we forbid / in expanded server URL variables like we do in path ones, and even if we do forbid it, there are at least several different ways this could play out:

{start}/foo

• simple/foo (relative path reference)
• example.com/foo (scheme-relative refrence)
• https://example.com/foo (full URI)
• /absolute/foo (absolute path, assuming / is valid)

You can't tell how to resolve the reference until the variables have been expanded.

[karenetheridge]

Again though, you can't match a URI to a template pattern, to figure out what the values of those template variables should be, until the entire pattern is present.

Clearly the entire concept of server urls needs to be rethought, or some extra restrictions added, to make this actually workable in reality.

[karenetheridge]

While thinking through this more I also realized that server urls (and path templates too) should probably be ascii-only (even more restrictive than that actually as the list of permitted characters is a subset of ascii) if we ever expect them to match against a URI - i.e. all other characters should be %-url-encoded. We lost this when we removed the "format": "uri-reference" on server urls in order to accomodate { and }.