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?

For me it depends a bit on where and how the links would be used. I find the first easier to read as a human, while the second one is probably a bit easier to use in code. If I have to pick between the two, I'd go for easier on humans.

I don't really like the schema-like approach for the issues-board in the example. (if that is indeed the meaning of that url, I have no way to be sure). I'd prefer that the contents of 'rel' is something human-readable another attribute where the schema information can go, something like:

{"rel":"issues", "schema":"https://archive.org/services/purl/purl/bll/resource/issues-board", "href": "https://github.com/beakerbrowser/beakerbrowser.com/issues"}

How about doing it like JSON API? This is very similar to option 2.

Where specified, a links member can be used to represent links. The value of each links member MUST be an object (a “links object”).

Each member of a links object is a “link”. A link MUST be represented as either:

• a string containing the link’s URL.
• an object (“link object”) which can contain the following members:
  • href: a string containing the link’s URL.
  • meta: a meta object containing non-standard meta-information about the link.

The following self link is simply a URL:

"links": {
  "self": "http://example.com/posts"
}

The following related link includes a URL as well as meta-information about a related resource collection:

"links": {
  "related": {
    "href": "http://example.com/articles/1/comments",
    "meta": {
      "count": 10
    }
  }
}

EDIT: actually, the "meta" field is useless, you can just add other keys straight in the object - that's exactly option 2 then.

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