Introduce constraints for Server Object url fixed field

[char0n]

I went ahead with this suggestion, as it is something that is not obvious from reading the OpenAPI spec, but it becomes obvious for the tooling authors during implementations.

Server Object.url field is defined as A URL to the target host.

OpenAPI further stipulates:

Unless specified otherwise, all fields that are URLs MAY be relative references as defined by RFC3986

Looking at RFC 3986, the Server Object.url can be one of the following:

URI           = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
relative-ref  = relative-part [ "?" query ] [ "#" fragment ]

Both of these non-terminals allow query and fragment. But effectively, we cannot allow them as OpenAPI further stipulates:

The path is appended to the URL from the Server Object in order to construct the full URL

Appending to URL or resolved relative reference containing query or fragment will end up corrupting the resulting URL.

---

There is another aspect of Server Object.url, and that's being Scheme-Based Normalization. When we define server URL as https://exmaple.com/, the tooling tends to remove the last character from the URL, if the character=/ before the path from Paths Object is appended to it. This is possible because of equivalence as described by Scheme-Based Normalization.

// server URL
http://example.com/

// paths
/path1
/path2

// we want to end up here
http://example.com/path1
http://example.com/path2

// we might end up here
http://example.com//path1
http://example.com//path2

AFAICT we cannot apply Scheme-Based Normalization to URL like http://example.com/initial-path. http://example.com/initial-path is not equivalent anymore to http://example.com/initial-path/.

I guess my question is, if we shouldn't restrict Server Object.url not to end with explicit /?

[char0n]

@ralfhandl thanks, what about the Scheme-Based Normalization issue? Do you think it is warranted to verbalize this into a url field description? Something like

This URL SHOULD NOT end with / character.

[miqui]

Perhaps we should wait until the next tdc to merge?

[miqui]

@baywet ping! check it out as well.

[miqui]

I might have missed this, but this fixed should target 3.2 only? (cc: @ralfhandl , @lornajane )

[baywet]

Changes look good, but I think the wrong branch is being targeted at the moment.

[baywet]

Some more context around the branches: I asked that same specific question on the TDC call a couple of weeks ago. The agreement we came to with @ralfhandl and @handrews was that, unless things are specific to a version of the spec, they should target 3.2-dev. Once 3.2-dev is released, all the changes that can be applied to 3.1 will be collected and applied in a single shot to avoid confusion. They might also be applied to 3.0, even though we agreed last time that 3.0.4 was the last release.

[karenetheridge]

I guess my question is, if we shouldn't restrict Server Object.url not to end with explicit /?

How about something like "Server Object.url values that end with / MUST be treated as equivalent to values without a trailing / when prepended to path values" (or "path templates"?) ?

This relates to what we need to when matching request URIs against /paths/<path template> entries in the absence of any Server objects -- for a request URI of "https://example.com", the path portion of the URI is not "" but rather "/", when considering a potential match against Paths Objects. (ref https://github.com/karenetheridge/OpenAPI-Modern/blob/v0.076/lib/OpenAPI/Modern.pm#L536)