Wrong example when trailing slash and no path?

[mokkabonna]

Not sure if this is wrong or not, but might need to be changed to be consistent. It is although a very minor issue.

json-schema-spec/jsonschema-hyperschema.xml

Lines 1593 to 1606 in 7a6c26c

	{
	"contextUri": "https://api.example.com",
	"contextPointer": "",
	"rel": "self",
	"targetUri": "https://api.example.com",
	"attachmentPointer": ""
	},
	{
	"contextUri": "https://api.example.com",
	"contextPointer": "",
	"rel": "about",
	"targetUri": "https://api.example.com/docs",
	"attachmentPointer": ""
	}

Here the contextUri is set to https://api.example.com (no trailing slash) The base has a trailing slash. I know the slash can be omitted if the path is empty. But in reality the slash is there in those cases, just omitted. For instance when doing curl example.com -Iv it produces HEAD / HTTP/1.1 Chrome does the same.

Especially when the base contains a trailing slash the example should IMO contain a trailing slash as well.

So the suggested change:

{
        "contextUri": "https://api.example.com/",
        "contextPointer": "",
        "rel": "self",
        "targetUri": "https://api.example.com/",
        "attachmentPointer": ""
}

[handrews]

@mokkabonna I'm not sure which thing I should fix here. In general, I usually see the / left off. For the base URI I want to show a trailing slash (because it's what you usually want for URI reference resolution as opposed to concatenation), so maybe put a path component there in which case it's not ambiguous.

But you're right that whatever it is, it should be consistent.

[Relequestual]

I would prefer for the slash to be left off. Personal preference though.

[handrews]

The case of an empty path component is weird and confusing, so I'm going to add a path component on the base. What I want to show is how you need to have a trailing slash on the base and not have a leading slash on your relative references in order to get relative references to (effectively) append.

A number of systems, notably OpenAPI, deviate from this, require a no trailing slash on the base, and require a leading slash on the pseudo-relative URI. And then they concatenate it. Which is completely in violation of RFC 3986, so I want to show how it is supposed to work.

@Relequestual I don't like trailing slashes in resource URIs either, but unfortunately this is a really annoying corner of RFC 3986: there is absolutely no way to just trim a trailing slash off of a base URI that has a path component. But if anything, this makes it more important to show the proper resolution behavior. It's rare to end up with just the base URI anyway. Usually you will have at most one such URI (for the entry point resource).

So either you duplicate last part of the path (but without the trailing slash) if you really want to avoid it, and just make sure not to let it get out of sync with base, or you just deal with the trailing slash on that one and only leave off the rest. It really annoys me.

[handrews]

OK I see two possibilities here, and given that whatever we use an example will probably be the de-facto best practice, I figure I'll float both here rather than just putting on in a PR.

This is a sensible way, but you end up with a trailing slash for the entry point resource (assuming its URI is the base URI). Or you have to duplicate the base URI there (or at least the last component).

This is a general problem whenever you try to go up the path with "..", it's just most likely to appear in this example.

A third option would be to sidestep it entirely and give the entry point a URI under the base URI, which might be the simplest for an example. There's no real reason that the entry point has to be the base URI.

Here are all three options:

{
    "base": "https://example.com/api/",
    "links": [{
        "$comment": "entry point, no duplication, yields https://example.com/api/",
        "href": "",
    }, {
        "$comment": "entry point, with duplication, yields https://example.com/api",
        "href": "../api",
    }, {
        "$comment": "entry point != base, yields https://example.com/api/entry",
        "href": "entry"
    }]
}

I'm leaning toward giving the entry point its own URI. Hyper-Schema is not responsible for advising people on this weirdness.

[handrews]

Merged #678