dat.json-links.md

Dat.json links field

We've been finding ourselves needing a lot of links on Dat sites. For instance, we want a way to specify the issues board for an app, or a place to pay authors.

We're thinking about adding a links field to the dat.json to keep this unified.

Approach 1, as an array:

{
  "title": "Beaker browser homepage",
  "links": [
    {"rel": "payment", "href": "https://opencollective.com/beaker"},
    {"rel": "author", "href": "dat://taravancil.com", "title": "Tara Vancil"},
    {"rel": "author", "href": "dat://paulfrazee.com", "title": "Paul Frazee"},
    {"rel": "https://archive.org/services/purl/purl/bll/resource/issues-board", "href": "https://github.com/beakerbrowser/beakerbrowser.com/issues"}
   ]
}

Approach 2, as an object with the "rel" as key:

{
  "title": "Beaker browser homepage",
  "links": {
    "payment": "https://opencollective.com/beaker",
    "author": [
      {"href": "dat://taravancil.com", "title": "Tara Vancil"},
      "dat://paulfrazee.com"
    ],
    "https://archive.org/services/purl/purl/bll/resource/issues-board": "https://github.com/beakerbrowser/beakerbrowser.com/issues"
  }
}

Any opinions?

Thinking about this a bit more, I would strongly tend towards approach 2.

In code terms: If I want to get all the authors in the example object...

• in approach 1, I'd have to do links.filter(link => link.rel === 'author') or some other trickery,
• while in approach 2, I can just get links.author.

(I think this is exactly what @jondashkyle means by more easily addressable)

In human terms: If you already know how JSON works, you don't need to know what rel or href mean in approach 2. They are meaningless acronyms (...what do they even stand for?). If you need extra metadata, then sure, href is a good choice exactly because it's so meaningless. Giving every link a name/purpose will make it a lot easier to "standardize" on specific link types. I for one would want "author" (or even "donate"/"payment"!) links to be universally adopted across the beakerweb :)

I may have missed the context, but am curious whether you are trying to have the links defined in dat.json be equivalent to Web Links as used in http headers (rfc8288)? Should one be able to convert between the two in either direction?

Some notes regarding making a consistent mapping with web links:

• Is the context (the resource the link 'points from') always the root URI of the dat? Can one also define the anchor attribute to create a link from another resource? Might be a nice future addition, as it allows specifying links from resources within the dat (though you may also want to be able to define them in subfolders etc.).
• Links may have multiple rels. This should not be a problem, as this is equivalent to multiple links, so in approach #2 you would simply duplicate the link for each rel.
• This CoRE draft is all about mapping web links to json and cbor, so it may be worth borrowing their approach. Their json example looks equivalent to approach #1.
• This article mentions a few other approaches for embedding links in json. Not all approaches seem to care about creating a consistent mapping with web links though.

Good feedback all, appreciate it