WebURL Documentation Beta

Structure Web​URL.​JSModel

public struct JSModel 

An interface to this URL whose properties have the same behaviour as the JavaScript URL class described in the URL Standard.

The other APIs exposed by WebURL are preferred over this interface, as they are designed to better match the expectations of Swift developers. JavaScript is JavaScript, and what is useful or expected functionality in that language may be undesirable and surprising in contexts where Swift is used. It is also subject to legacy and browser interoperability considerations which do not apply to the WebURL API.

The primary purpose of this API is to facilitate testing (this API is tested directly against the common web-platform-tests used by major browsers to ensure compliance with the standard), and to aid developers porting applications from JavaScript or other languages, or interoperating with them, since this functionality exposed by this interface matches the JavaScript URL class.

The main differences between the Swift WebURL API and the JavaScript URL class are:

  • WebURL uses nil to represent not-present values, rather than using empty strings.

    This can be a more accurate description of components which keep their delimiter even when empty. For example, in JavaScript, the URLs "http://example.com/" and "http://example.com/?" both return an empty string for the search property, even though the "?" query delimiter is present in one of the strings and not in the other. This has secondary effects, such as url.search = url.search potentially changing the serialized URL string. WebURL models the former as nil (to mean "not present"), and the latter as an empty string, to more accurately describe the structure of the URL. URLs are confusing and complex enough.

  • WebURL does not include delimiters in its components.

    For example, the query string's leading "?" is part of the JavaScript URL class's .search property, but not part of WebURL's .query property. We assume that most consumers of the query or fragment strings are going to drop this delimiter as the first thing that they do, and it also happens to match the behaviour of Foundation's URL type.

    For setters, JavaScript also drops a leading "?" or "#" delimiter when setting the search or hash. WebURL does not - the value you provide is the value that will be set, with percent-encoding if necessary to make it work.

    Note that this only applies to 3 components, all of which have different names between JavaScript's URL class and WebURL (protocol vs scheme, search vs query, hash vs fragment).

  • WebURL does not filter ASCII whitespace characters in component setters.

    In JavaScript, you can set url.search = "\t\thello\n", and the tabs and newlines will be silently removed. WebURL percent-encodes those characters, like it does for other disallowed characters, so they are maintained in the component's value.

  • WebURL does not ignore trailing content when setting a component.

    In the following example, JavaScript's URL class finds a hostname at the start of the given new value - but the new value also includes a path and query. JavaScript detects these, but silently drops them while succesfully changing the hostname. This happens for many (but not all) of the setters in the JavaScript model.

    var url = new URL("http://example.com/hello/world?weather=sunny");
    url.hostname = "test.com/some/path?query";
    url.href; // "http://test.com/hello/world?weather=sunny"

    Continuing with the theme of WebURL component setters being stricter about setting precisely the string that you give them, this operation would fail if setting WebURL.hostname, as "/" is a forbidden host code-point.

If these deviations sound pretty reasonable to you, and you do not have a compelling need for something which exactly matches the JavaScript model, use the WebURL interface instead.

Member Of


A Uniform Resource Locator (URL) is a universal identifier, which often describes the location of a resource.

Conforms To




public init?(_ string: String, base: String?) 

Constructs a new URL by parsing string against the given base URL string.

If base is nil, this is equivalent to WebURL(string). Otherwise, it is equivalent to WebURL(base)?.resolve(string).



public var swiftModel: WebURL 

The WebURL interface to this URL, with properties and functionality tailored to Swift developers.


public var description: String 


public var href: String 

Gets and sets the serialized URL.


public var origin: String 

Gets the read-only serialization of the URL's origin.


public var username: String 

Gets and sets the username portion of the URL.


public var password: String 

Gets and sets the password portion of the URL.


public var scheme: String 

Gets and sets the protocol portion of the URL.


public var hostname: String 

Gets and sets the host name portion of the URL. The key difference between url.host and url.hostname is that url.hostname does not include the port.


public var host: String 

Gets the host portion of the URL.


public var port: String 

Gets and sets the port portion of the URL.


public var pathname: String 

Gets and sets the path portion of the URL.


public var search: String 

Gets and sets the serialized query portion of the URL.


public var hash: String 

Gets and sets the fragment portion of the URL.



public func hash(into hasher: inout Hasher) 



public static func == (lhs: Self, rhs: Self) -> Bool