From 107678f560e5ac06ecc6cafe7ca2e43956b79bfe Mon Sep 17 00:00:00 2001
From: Brad Fitzpatrick <brad@danga.com>
Date: Wed, 1 Dec 2010 21:14:07 -0800
Subject: [PATCH] more schema docs

---
 doc/schema/claims/TODO   | 50 ++++++++++++++++++++++++++++++++++++++++
 doc/schema/keep.txt      | 16 +++++++++++++
 doc/schema/permanode.txt | 15 ++++++++++++
 3 files changed, 81 insertions(+)
 create mode 100644 doc/schema/claims/TODO
 create mode 100644 doc/schema/keep.txt
 create mode 100644 doc/schema/permanode.txt

diff --git a/doc/schema/claims/TODO b/doc/schema/claims/TODO
new file mode 100644
index 000000000..69b7e6b63
--- /dev/null
+++ b/doc/schema/claims/TODO
@@ -0,0 +1,50 @@
+TODO:
+-----
+Clean this up and/or break into separate files.
+
+
+Old notes from July doc:
+------------------------
+Claim types:
+permanode-become:
+   -- implies either:
+        1) switching from typeless/lifeless virgin pnode into something (dynamic set, filesystem tree, etc)
+        2) changing versions of that base metadata (new filesystem snapshot)
+  -- ‘permaNode’ is the thing that is changing
+  -- ‘contents’ is the current node that represents what permaNode changes to
+set-membership: add a blobref to a dynamic set
+  -- “permaNode” is blobref of the dynamic set
+delete-claim:  delete another claim (target is claim to delete)
+  -- “contents” is the claim blobref you’re deleting
+{set,add}-attribute:
+  -- attach a piece of metadata to something.
+  -- use set-attribute for single-valued attributes only: highest dated claim wins (of trusted person) e.g.  “title”, “description”
+  -- use add-attribute for multi-valued things. e.g. “tag”
+
+Tagging something:
+{“claimType”: “add-attribute”, //
+  “attribute”: “tag”,  // utf-8, should have list of valid attributes names, preferrably not made up by us (open social spec?)
+  “value”: “funny”,  // value that doesn’t have lasting value
+  “valueRef”: “sha1-blobref”,  // hefty reference to a lasting value
+ 
+  “claimer?”: “sha1-of-the-dude-who’s-signing”,
+  “claimDate”: “2010-07-10T17:20:03.9212Z”,
+  “claimType”, “permanode-become”,
+  “permaNode”: “sha1-pnode”,
+}
+
+filesystem root claim:
+{
+  “camliVersion”: 1,
+  “camliType”: “claim”,
+
+  // Stuff for camliType “claim”:
+  “claimDate”: “2010-07-10T17:20:03.9212Z”,  // redundant with data in ascii armored "camliSig".  TODO: resolve
+  “claimType”, “permanode-become”,
+
+   // Stuff for “permanode-become”:
+  “permaNode”: “sha1-pnode”,
+  “contents”: “sha1-fs-node”
+
+,"camliSigner": "digalg-blobref-to-ascii-armor-public-key-of-signer",
+"camliSig": "......"}
diff --git a/doc/schema/keep.txt b/doc/schema/keep.txt
new file mode 100644
index 000000000..0863595cb
--- /dev/null
+++ b/doc/schema/keep.txt
@@ -0,0 +1,16 @@
+A signed "keep" edge for GC/indexing purposes.  Expressed a user's
+intent to keep an object.
+
+This is not the only way to keep an object alive for the purposes of
+GC.  Permanodes (signed by a user) are also part of that user's roots,
+and anything they reference (including blobs via "become" claims on
+those permanodes)
+
+This is just the most explicit way when you're not modeling the data
+with permanodes.
+
+{"camliVersion": 1,
+ "camliType": "keep",
+ "target": "digalg-blobref-of-thing-to-keep",
+<REQUIRED-JSON-SIGNATURE>}
+
diff --git a/doc/schema/permanode.txt b/doc/schema/permanode.txt
new file mode 100644
index 000000000..c85e90188
--- /dev/null
+++ b/doc/schema/permanode.txt
@@ -0,0 +1,15 @@
+The idea of a permanode is that it's the anchor from which you build
+mutable objects.  To serve as a reliable (consistently nameable)
+object it must have no mutable state itself.
+
+{"camliVersion": 1,
+ "camliType": "permanode",
+
+ // Required.  Any random string, to force the sha1 of this
+ // node to be unique.  Note that the date in the ASCI-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>}
+