perkeep/doc/schema/permanode.md

Permanodes

Permanodes are how Perkeep models mutable data on top of an immutable, content-addressable datastore. The data is modeled using nodes with two camliTypes: permanode and claim.

Permanode

A permanode is an anchor from which you build mutable objects. To serve as a reliable (consistently nameable) object, it must have no mutable state itself. In fact, a permanode is really just a signed random number.

{"camliVersion": 1,
 "camliType": "permanode",

 // Required.  Any random string, to force the digest of this
 // node to be unique.  Note that the date in the ASCII-armored
 // GPG JSON signature will already help it be unique, so this
 // doesn't need to be a great random.
 "random": "615e05c68c8411df81a2001b639d041f"

<REQUIRED-JSON-SIGNATURE>}

Claim

A claim is any signed JSON schema blob. One common use is modifying "attributes" on a permanode. The state of a permanode is the result of combining all attribute-modifying claims which reference it, in order. Claim nodes look something like this:

{"camliVersion": 1,
 "camliType": "claim",
 "camliSigner": "....",
 "claimDate": "2010-07-10T17:20:03.9212Z", // redundant with data in ascii armored "camliSig",
                                           // but required. more legible. takes precedence over
                                           // any date inferred from camliSig
 "permaNode": "sha1-xxxxxxx",        // what is being modified
 "claimType": "set-attribute",
 "attribute": "camliContent",
 "value": "sha1-yyyyyyy",
 "camliSig": .........}

All claims must be signed.

The anagrammatical property claimType defines what the claim does, and is one of the following:

• add-attribute: adds a value to a multi-valued attribute (e.g. "tag")

• set-attribute: set a single-valued attribute. equivalent to "del-attribute" of "attribute" and then add-attribute.

• del-attribute: deletes all values of "attribute", if no "value" given, or just the provided "value" if multi-valued

• multi: atomically do multiple add/set/del from above on potentially different permanodes. NOT IMPLEMENTED YET (see issue 110), but it might look like:

    {"camliVersion": 1,
     "camliType": "claim",
     "claimType": "multi",
     "claimDate": "2013-02-24T17:20:03.9212Z",
     "claims": [
          {"claimType": "set-attribute",
           "permanode": "sha1-xxxxxx",
           "attribute": "foo",
           "value": "fooValue"},
          {"claimType": "add-attribute",
           "permanode": "sha1-yyyyy",
           "attribute": "tag",
           "value": "funny"}
     ],
     "camliSig": .........}
  

Attributes

A permanode can have any attribute you like, but here are the ones that currently mean something to Perkeep:

• tag: A set of zero or more keywords (or phrases) indexed completely, for searching by tag. No HTML.

• title: A name given to the permanode. No HTML.

• description: An account of the permanode. It may include but is not limited to: an abstract, a table of contents, or a free-text account of the resource. No HTML.

• camliContent: A reference to another blob. If a permanode has this attribute, it's considered a pointer to its camliContent value.

• camliMember: A reference to another permanode. This indicates that the referenced permanode is a dynamic set, and we're a part of it.

• camliPath: camliPath attributes are set on permanodes which represent dynamic directories. If a permanode has attributes:

    camliPath:dir2 = $blobref_dir2_permandode
    camliPath:bar.txt = $blobref_bartxt_permanode
  

  It will appear as a directory containing "dir2" and "bar.txt".

  These are used by a few things, including the web UI, the "publish" code (declaring you want a photo at a URL and then the HTTP front end resolving each directory link in http://myhostname.com/pics/x/y/x/funny.jpg), and the FUSE read/write filesystem code.

• camliRoot: A root name for the permanode. This will cause it to show up as a named folder in the FUSE filesystem under roots/. Creating a directory in roots/ will cause a new permanode to be created with this attr set. You can also browse roots in the web UI.