Clarify scope of API define in the spec or split specs

[alercah]

I believe that some confusion has resulted because of the fact that the spec includes, in addition to the definition and semantics of the URL itself, an IDL API which is implied as an API to all URLs, despite IDL only really being a spec for Web APIs. I have heard someone somewhere, though I forget where, express that because it is IDL it is non-normative when not integrating against the web technologies that use such APIs.

The web-centric design causes some difficulty (e.g. servo/rust-url#577) because specific API decisions are made with web APIs in mind. The issue I just linked runs into this problem where code is relying on being able to exchange a special scheme for a non-special one, which is not really supported (or completely unsupported?) in the API provided, but shouldn't be seen as an inherently invalid operation. URLs are a technology that stretches far beyond the browser-based web, and their general usage shouldn't, in my view, be limited by web-specific decisions.

There's also an argument that IDL does not translate well to certain languages, such as those with value-based objects for which "set" is not a meaningful concept. There's additionally an issue of backwards-compatibility: many languages have strong backwards-compatibolity guarantees and cannot commit to a spec that implements no such guarantees.

Ideally, I think the spec should make clear that the IDL API is only for web, and language libraries should design their own APIs as they feel appropriate around the core concepts. As an alternative, it should go in the direction of insisting that all APIs should match its semantics exactly, and clearly specifying that this is true regardless of its use of IDL. Personally, if it went in this direction, I would be inclined to argue against its widespread adoption outside of the context of the Web and support further development of the canonical specification only through the IETF RFC process.

I thought I had brought this up before on an issue here, but I can't find it, so perhaps not. Apologies if it's a duplicate.

[domenic]

It seems a bit weird that every spec that uses Web IDL to specify a JavaScript API would need to re-explain how Web IDL works?

[alercah]

Most specs aren't defining general technologies that have broad use beyond the network of web standards. This requires a bit more care. The abstract of this spec, for instance, says that it defines (emphasis mine) "The URL Standard defines URLs, domains, IP addresses, the application/x-www-form-urlencoded format, and their API." One could be forgiven for interpreting this as implying that it defines a single canonical API for URLs across all languages.

Similarly, section 6.3 is a bit unclear as to whether it is generally referring to web standards, or all standards of any form (which might include, say, an International Standard for a programming language like C++, notwithstanding that I doubt ISO rules would allow normative references to living standards).

[annevk]

I suggest we reuse the wording from https://encoding.spec.whatwg.org/#api.