Tags: Data Model, UI/UX, Permanent Data

Our system supports different URL formats for linking to various things like documents, users, blocks, etc.

Hypermedia URLs should be mappable to Web URLs and vice-versa because we want to be interoperable with the Web. To avoid web link rot, all permanent data must use Hypermedia URLs as much as possible.

To support more seamless interop with the Web, some Paths for documents should not be used. We may call it a must, but we always have to be resilient to situations when someone creates a path with the reserved word. Our application should disallow or at least discourage users to create paths with the following prefixes:

/ipfs/ path is reserved for resolving IPFS blobs by CID. Same as IPFS Gateway does.

/ipns/ path is reserved for the same purpose as IPFS but for resolving IPNS name. We don’t use IPNS so we don’t really care, but still it’s useful to reserve this name to avoid any future problems.

/hm/ path is reserved for HM ↔ WEB URL mappings (discussed next).

/.well-known/ path is reserved to support the well-known URI convention.

Any HM URL can be transformed into a Web URL by replacing hm:// with /hm/ and using the resulting string as a URL path, concatenating it with the base web URL.

E.g. hm://aliceaccount/wunderland?v=deadbeef#block-id-1 could be hosted on example.com web domain as https://example.com/hm/aliceaccount/wunderland?v=deadbeef#block-id-i1.

Our servers need to be able to display any HM document, not only those that are handled by this server’s Account. E.g. if my site shows a document that has a link to another doc in another Account, which may not have a site, then I need to display it in my own site.

Because doc URL include the account ID I need a way to resolve a document with <accounts><path> pair. At the same time I don’t want to use my own account ID in the URL for my own docs, because I want pretty URLs. I want https://mysite.com/about to resolve to /about in my Account.

Hypermedia URLs are a subset of the much broader URL Spec.

HM-URL = doc-url

doc-url = "hm://" account-id [path] ["?" doc-query] ["#" doc-fragment]
doc-query = "v=" version-id
doc-fragment = block-id [range-selector]