Documentation / /
Web APIs

dat.json

Websites and applications served over dat:// can include a manifest file to specify metadata and configure special behaviors. The file must be located at /dat.json in the website or application root.

Beaker automatically creates and manages the manifest for Dat archives created with the DatArchive Web API.

Example:

dat.json
{
  "title": "My website",
  "description": "A simple website built with the Beaker Browser",
  "type": ["website"],
  "links": {
    "license": [{
      "href": "http://creativecommons.org/licenses/by-nc/2.5/",
      "title": "CC BY-NC 2.5"
    }]
  },
  "fallback_page": "/404.html",
  "web_root": "/public",
  "content_security_policy": "default-src 'self'",
  "experimental": {
    "apis": ["datPeers", "globalFetch", "library"]
  }
}

title

A short and descriptive human-friendly title. Can be read with getInfo() and changed with configure().

{
  "title": "My cool site"
}

description

A description of the Dat archive. Can be read with getInfo() and changed with configure().

{
  "description": "The absolute best place to find cat pictures."
}

type

A list of ‘type’ strings. Can be read with getInfo() and changed with [configure()(dat.html#configure).

Type strings are experimental. They were introduced to Beaker as a way to categorize archives, and can be used as a filter in selectArchive(). You can list multiple types on an archive.

{
  "type": ["user-profile", "fritter-user-profile"]
}

What are types used for?

They are used as a filter in selectArchive(), similar to how file-extensions are used in operating system “open file” dialogs. They are also a way for apps to identify the kind of data or content in an archive using getInfo().

What types can I use?

There are no official types. We recommend including a short string which identifies the general kind of data being stored, plus one or more long strings which help identify the schema of the data. For example, a social media app called ‘Fritter’ might use "user-profile" and "fritter-user-profile".

An object containing a set of Web links from the Dat. Can be read with getInfo() and changed with configure()/.

The links object is a mapping of “rel” values to arrays of link objects, as follows:

{
  "rel-type": [{"href": "https://example.com/"}]
}

The links field follows the same schema as the link element, so any attribute which applies to a <link> will apply to these values. The one difference is how the rel value is handled: in the links object, the rel is used as the key. Only one rel value should be used.

If a link has additional rel values, it can specify them using the rel field on the link object. For instance, a link with the rel value of "foo bar baz" would look like this:

{
  "foo": [{"href": "https://example.com/", "rel": "bar baz"}]
}

Links can be duplicated, and so it would also be possible to handle this case with 3 different link objects:

{
  "foo": [{"href": "https://example.com/"}],
  "bar": [{"href": "https://example.com/"}],
  "baz": [{"href": "https://example.com/"}]
}

fallback_page

The path to a fallback page to serve instead of Beaker’s default 404 page.

{
  "fallback_page": "/404.html"
}

web_root

The path of the folder from which all requests should be served.

{
  "web_root": "/public"
}

content_security_policy

The security policy for the website. Learn more about using Content Security Policy.

{
  "content_security_policy": "default-src 'self'; script-src 'self' https://example.com"
}

experimental.apis

A list of experimental APIs. To use an experimental API, you must list one of the following strings in the experimental.apis field:

{
  "experimental": {
    "apis": ["datPeers", "globalFetch", "library"]
  }
}

To learn more, read this guide about using experimental APIs.

Experimental APIs may change quickly or be removed entirely. You should not depend on an experimental API for stability.