# 🗺️ Feature/Property-Driven Support for URIs in Content Addressing Systems

## Introduction

Content-addressable systems identify data by the hash of its contents, enabling verifiable and immutable references. While powerful, these systems often rely on external discovery layers to locate the actual bytes—despite the fact that clients may already know one or more potential sources.

Several groups have explored and concluded that having a CID with extra information in a long string is a good idea, typically as an URI. These approaches aim to simplify fetching content from a content provider, improve resilience and decrease number of hops.

## Approaches

This document catalogs features and properties that MAY be desirable for URIs in content-addressable systems. While the URI formats explored here serve different design goals and use cases, this comparison aims to highlight their respective strengths and trade-offs.

The URI approaches considered are:

- [Provider-hinted URIs](https://github.com/vasco-santos/provider-hinted-uri/blob/main/EXPLORATION.md) (with multiaddr and HTTP string query parameters)
- [RASL](https://dasl.ing/rasl.html)
- Magnet Links

A provider-hinted URI using query parameters MAY look like:

{scheme}://bafy...
    ?provider=/dns/my-hash-stream-server.com/tcp/443/https/tag/tgwV1
    &provider=/ip4/98.10.2.1/tcp/8000/ws/tag/bitswap

or simply combine providers as strings and Multiaddrs:

{scheme}://bafk...
  ?provider=https://foo.bar/example-framework.js
  &provider=/dns/example.com/tcp/443/https/http-path/example-framework.js/tag/octets

As scheme, `ipfs://` is preferrable, however some contexts where IPFS association is undesirable ([n0](https://n0.computer/)) or where alternative CID encodings are used ([S5](https://github.com/s5-dev/S5)) could be considered.

A RASL URI MAY look like:

web+rasl://bafkreifn5yxi7nkftsn46b6x26grda57ict7md2xuvfbsgkiahe2e7vnq4;berjon.com,bsky.app/

A Magnet Link MAY look like:

magnet:?xt=urn:btih:<infohash>&dn=<display name>&tr=<tracker URL>&ws=<web seed>

## Feature/Property Matrix

Each URI format presents different advantages and limitations depending on the intended usage. The table below outlines a set of desirable features and how well each approach supports them.

Note: Column 1 (`ProvHint as MA`) and 2 (`ProvHint as String`) can be combined in a single URI.

| Feature / Property | ProvHint as MA | ProvHint as String | RASL | Magnet Links |
| ---------------------------------------- | ----------------- | ---------------------- | ---- | ------------- |
| Encodes CID | ✅ | ✅ | ✅ | ✅ |
| URI MAY encode multiple fetch hints | ✅ | ✅ | ❌ | ✅ (limited) |
| Self-contained, no translation required | ✅ | ✅ | ❌ | ✅ |
| Supports non-HTTP transports | ✅ | ❌ | ❌ | ✅ |
| Human-readable/editable | ✅ | ✅ | ❌ | ⚠️ |
| Supports optional tags | ✅ | ❌ | ❌ | ❌ |
| URI-compatible with gateway URLs | ✅ | ✅ | ❌ | ❌ |
| Easily shareable in CLI/tools | ✅ | ✅ | ✅ | ⚠️ |
| Fallback/resilience support | ✅ | ✅ | ⚠️ | ❌ |
| Discovery extensibility for clients | ✅ | ✅ | ❌ | ✅ |
| Publisher ease of hint updates | ⚠️ | ⚠️ | ✅ | ⚠️ |
| Does not require multiaddr knowledge | ❌ | ✅ | ✅ | ✅ |

> ✅ = full support, ⚠️ = partial or limited support, ❌ = not supported

### Feature details

### Encodes CID

Indicates whether the format includes a content identifier as a core element of addressing.

### URI MAY encode multiple fetch hints

Supports embedding multiple optional provider hints for locating content via different hosts or transports.

### Self-contained, no translation required

Clients can directly retrieve content from providers without needing additional translation or interaction steps (e.g. no intermediate resolution layers).

### Supports non-HTTP transports

Can include or imply transports beyond HTTP (e.g., libp2p, BitTorrent), enabling decentralized or peer-to-peer data transfer.

### Human-readable/editable

The URI structure is simple, direct and readable enough for humans to manually inspect, understand, and eventually modify it.

### Supports optional tags

Allows the URI Hint to optionally specify protocol for fetching the content, enabling clients to not be required to perform negotiation or probing.

### URI-compatible with IPFS gateway URLs

The URI can be used as is with IPFS gateway URLs, even if they ignore the capabilities this smart URI tries to provide.

### Fallback/resilience support

Clients can use embedded hints to locate content even when discovery services are unavailable.

### Discovery extensibility for clients

Hints can be safely ignored by clients that don’t support them, enabling forward compatibility without breaking existing systems.

### Publisher ease of hint updates

Indicates how easily the content publisher can update hints without requiring much changes.

### Does not require multiaddr knowledge

Supports usage without needing to understand or construct multiaddrs, making it more approachable to developers unfamiliar with these conventions.

---

All formats considered here are valid options depending on the specific requirements and constraints of a system. While query parameter-based URIs offer flexibility and protocol richness, RASL and magnet links provide valuable benefits in ease of use or legacy support. The goal is not to rank these approaches, but to provide visibility into their trade-offs so that system designers can choose the most appropriate option for their use case.