Function parameters names: $uri vs. $href

[ChristianGruen]

I was asked about the difference between the function parameter names $href and $uri…

• fn:doc($href) (“Retrieves a document using a URI supplied as an xs:string…”); fn:unparsed-text($href); others
• fn:collection($uri), fn:uri-collection($uri); others

…and I couldn’t give a convincing answer. At least in BaseX, both fn:doc and fn:collection can be used interchangeably to address single resources (but things change when the target contains multiple resources).

Would it be reasonable to rename $href to $uri, or are there reasons why we need to differ those two?

If we rename the parameter, fn:resolve-uri may be the only function using $href (maybe even here, $uri could work?).

[ndw]

I don't think there's an interesting technical distinction. My impression is that we prefer $href when the thing being identified is likely to be a page that exists on the web. This leverages the experience of users familiar with <a href=...>. We tend to prefer $uri when the identifier is just an identifier and may not have a useful hypertext representation on the web, things like collation identifiers.

If users are attempting to divine meaning from the argument names and finding the differences confusing, I won't object to using one name consistently. Whether that would be a net win depends, I guess, on whether more or fewer people will be confused by doc($uri) because they have an immediate connection to href but not uri.

[benibela]

I always use url. everyone has heard of urls. But I guess url is not used in Xpath

[ndw]

Pedantically, url is a misnomer. It strongly implies that the things identified have a location, or can be located, which is not true of entirely abstract things that might be identified (like collations, for example). Back in the day, the distinction between URIs that referred to information resources that could be located by doing a GET request on a server and URIs that refered to abstractions like "peace", "love", and "understanding", not to mention things that (some would argue) are not information resources, like the corporeal form of the individual who wrote this comment, was a subject of intense debate.

[gimsieke]

https://en.wikipedia.org/wiki/HTTPRange-14

[gimsieke]

There are at least two different schools of thought:

The name is sound and smoke, / beclouding Heaven's glow

— Goethe: Faust (advocating for tolerance of differently named attributes)

Consistency over Correctness

— Internal rule at McKinsey & Company (advocating for same-named attributes even if some people argue that they have subtly differing meanings)

If different attribute names have been established for (purportedly) similar or maybe same things, I’d recommend to quench it with an editorial note that states that these are, by and large, the same things, and, mostly for historical reasons, one of them is called $uri and the other one is called $href.

[ChristianGruen]

The name is sound and smoke, / beclouding Heaven's glow — Goethe: Faust (advocating for tolerance of differently named attributes)

;-) …and it was introduced with “Feeling is all”.

mostly for historical reasons, one of them is called $uri and the other one is called $href.

Fortunately, we can ignore history this time, as the parameter names have become relevant only recently for the 4.0 feature to explicitly address a parameter in the function call: fn:doc(href := 'https://faust.org'). Once we choose names, we cannot change them anymore in future versions.

Your note was helpful. I looked up the 3.1 spec, and I noticed…

• fn:doc($uri)
• fn:collection($arg)

…that both parameter names were changed. However, the overall naming scheme is definitely more consistent now.

My personal preference would be McKinsey’s one (in addition, the result will still be correct).