Self-Describing Resource Locator

• 2025.8.2: Description for string escaping, type definitions and resolution. Added description for URL form.
• 2025.8.1: First version

An HTTP URL like this:

https://sebastian.graphics/blog/the-problem-with-wikipedia.html

…is described with SDRI like this:

/dns4/sebastian.graphics/https/blog$/the-problem-with-wikipedia.html

To break it up and explain each part:

# DNS resolve via default settings:
#     locally configured domain name server
#     UDP+TCP at port 53
# look for a domain named "sebastian.graphics"
/dns4/sebastian.graphics

# Use HTTPS with default setting:
#   TCP + TLS (version number negotiated) over port 443
# Use HTTP protocol; query for "blog/the-problem-with-wikipedia.html"
# the slash is escaped with "$"
/https/blog$/the-problem-with-wikipedia.html

In the example above /dns4 and /https are actually shorthands for often-used protocols; the fully qualified version would be something like this:

/ip4/{ns_ip}/53/dns4/sebastian.graphics/tcp+tls:*/443/http/blog$/the-problem-with-wikipedia.html

To break it down:

# use IPv4, locally configured domain name server ip
/ip4/{ns_ip}

# use port 53, which at this time produce an IPAddr w/ Port
/53

# use dns4, which would use the UDP+TCP combo on the
# previously specified port and the ip addr.
# look for "sebastian.graphics"
/dns4/sebastian.graphics

# on the produced IPv4 Address,
# use TCP and TLS (version determined by negotiation) at port 443
/tcp+tls:*/443

# use HTTP
# look for "blog/the-problem-with-wikipedia.html"
# the slash is escaped with "$".
/http/blog$/the-problem-with-wikipedia.html

And the examples listed at Multiformats website:

/ip4/127.0.0.1/udp/9090/quic       # IPv4 address using UDP on port 9090, with QUIC
/ip6/::1/tcp/3217                  # IPv6 address using TCP on port 3217
/ip4/127.0.0.1/tcp/80/http/baz.jpg # IPv4 address using TCP on port 80, accessing an HTTP resource
/dns4/foo.com/tcp/80/http/bar$/baz.jpg # DNS resolution (IPv4) using TCP on port 80, accessing an HTTP resource
/dns6/foo.com/tcp/443/https        # DNS resolution (IPv6) using TCP on port 443 for HTTPS
# NOTE: apparently the use of /https above is deprecated and replaced with /tls/http now?

…can be written as follows:

/ip4/127.0.0.1/udp+quic/9090
/ip6/::1/tcp/3217
/ip4/127.0.0.1/tcp:80/http/baz.jpg
/dns4/foo.com/tcp/80/bar$/baz.jpg
/dns6/foo.com/tcp+tls/443/http/

• An SDRL is composed of one or more step components ("step" for short), each of which describes an independent step of the process required to gain access to the resource it describes.
• Step components are composed of attribute components ("attribute" for short), which are different elements needed to describe that particular step to be completed, like the port number or the IP address.
• Within each step component, attributes are described in the order of from lower-level to higher-level. For example, to describe a step that involves HTTP, one would first specify IP, then TCP, and then HTTP at last.
• Each step is to be described "as its own thing"; for example, an HTTPS request to a domain name would involve DNS name resolving; in this case, the whole course of DNS resolution is specified with the HTTPS part being put at the end; the order of things would be IP-DNS-TCP&TLS-HTTP.

A few types are defined:

• IPv4Addr - IPv4 address. The lexical syntax of this type follows the convention of 4 period-separated decimal numbers in the range of 0 to 255.
• IPv6Addr - IPv6 address. The lexical syntax of this type follows RFC 5952.
• IPAddr - This type is defined as a union of IPv4Addr and IPv6Addr. Any IPv4Addr and any IPv6Addr matches with this type during type checking.
• Port - Port number. The lexical syntax of this type would be a decimal nubmer.
• Version - Version string. The lexical syntax of this type is not strictly defined, since different protocols can have different ways of versioning; but the string * is considered a valid Version, which means that the version of the protocol would be decided by negotiation at runtime.
• String - An fully escaped arbitrary string. Escaping is necessary to prevent certain queries (e.g. paths in HTTP) to be errorneously interpreted as an attribute.
  • To escape a string, all occurences of the character $ is to be replaced with $$, and all occurences of the character / is to be replaced with $/. To un-escape a string, simply perform the reverse action - replace all $/ with /, then all $$ with $.
  • Under situations where only ASCII is allowed for an SDRL, the encoding scheme in RFC 3986 is to be used to the unescaped string.
• 0 - A type that matches nothingness. (See section "Resolution").

A "catch-all" type, * (different from the value * of the Version Type) is also defined to match any subjects and the lack thereof (in cases when the attribute is the first attribute of the SDRL).

We allow arbitrary port number override. We define two special type constructors for it, written as follows:

• [type]/Port - An object of type [type] with a port, e.g. an IPv4 address with a port number would have a type of IPv4Addr/Port.
• [type]/Port? - An object of type [type], which may or may not come with a port. This types match with both [type] and [type]/Port.

With these two type constructors we have the following types:

IPv4Addr/Port   -   An IPv4 address with port
IPv6Addr/Port   -   An IPv6 address with port
IPv4Addr/Port?   -   An IPv4 address, which may or may not have a port
IPv6Addr/Port?   -   An IPv6 address, which may or may not have a port
TransLayerEndpoint/Port, TransLayerEndpoint/Port?
AppLayerEndpoint/Port, AppLayerEndpoint/Port?
DataEndpoint/Port, DataEndpoint/Port?

An attribute always uses the "latest" port number up till that point, unless a port number is provided as an argument. For example, the sequence of attributes /356/448/tcp contains two port number overrides (356 and 448, in that order) and an attribute of TCP; if there's no arguments for the /tcp part, then this TCP connection would use port number 448 (since it overrides the previously-set 356).

The different path components is described in the following form:

/...
    ArgumentTypes -> (SourceType -> TargetType)
    # Description of this path component.

The first line describes its syntax form. Within this syntax form, the arguments of a path component is enclosed in square brackets (which is not a part of the actual path). For example, the syntax of TCP+TLS is written as /tcp+tls:[ver]/[portno], but you write e.g. /tcp+tls:*/443 instead of /tcp+tls:[*]/[443].

The types of a path component's arguments is described w/ a n-tuple enclosed in parentheses and each type separated with comma. When there is only one argument, the parentheses are omitted. When there's no arguments, () is written instead.

SourceType describes the required type of whatever that comes before the path component, and TargetType describes the resulting type of appending this path component to that. The description of types are detailed above.

Multiple type description line of a path component may exist. As long as one of them is applicable, the whole path should be seen as without typing errors.

A few short hands can be defined as follow:

/https/[path...]
    # Equivalent to:
    #     /tcp+tls:443/http/[path...]

Imagine we run DNS over some HTTPS tunnel; we can describe it with SDRL like this:

/ip4/{some-ip}/tcp+tls:*/443/http/{some-path}/dns4/{some-domain}

The resolution process would be like this:

• In the beginning, the subject is empty (type 0)
• The source type of the first attribute, /ipv4/{some-ip}, is *. This matches with type 0. The subject is now an IPv4Addr, whose actual value is specified with {some-ip}.
• The second attribute would be /tcp+tls:*/443, whose source type is IPAddr or IPAddr/Port (both of which matches with IPv4Addr, but the resolution should opt for the more specific ones if possible) and produces an TransLayerEndpoint/Port. The subject is now an TCP+TLS endpoint at the IPv4 address {some-ip} and port 443.
• The third attribute would be /http/{some-path}, whose source type can be 0, IPAddr, IPAddr/Port and DataEndpoint. The type of the current subject is TransLayerEndpoint/Port, which matches with DataEndpoint. The subject is now an DataEndpoint.
• The fourth attribute would be /dns4/{some-domain}, whose source type can be 0, IPAddr, IPAddr/Port and DataEndpoint. The last one matches with the type of our current subject. This produces an IPv4Addr.

The overall result would thus be an IPv4Addr. This isn't an endpoint, but this behaviour is to be expected since it's a DNS query. Attributes for e.g. HTTP can follow after.