add terminology doc

doc/terminology.txt

@@ -0,0 +1,70 @@
+We use the following terms in our documentation and code:
+
+Blob: 0 or more bytes, with no extra metadata
+
+BlobRef: a reference to a blob, consisting of a cryptographic hash
+  function name and that hash function's digest of the blob's bytes,
+  in hex.  Examples of valid blobrefs include:
+
+     sha1-f1d2d2f924e986ac86fdf7b36c94bcdf32beec15
+     md5-d3b07384d113edec49eaa6238ad5ff00
+     sha256-b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c
+
+  Concatenating the two together with a hyphen is the common
+  representation, with both parts in all lower case.
+
+Object / Camli Object: a data structure consisting of keys/values
+  where values are string literals, numeric literals, other objects,
+  or arrays of values.  In Camli, these are serialized as JSON
+  everywhere.
+
+Object Blob / Camli Blob: the JSON serialation of a Camli Object.
+  This is just a normal JSON serialization (with any JSON
+  serialization library that's available), with the extra requirement
+  that the serialization must start with the 16 bytes:
+
+     {"camliVersion":
+
+  With no extra whitespace, no single quotes instead of doublequotes,
+  etc.  Those 16 bytes are the magic number[1] for Camli blobs.  As
+  JSON serialization libraries [sanely] won't let you specify the
+  order of keys in a dictionary, the camli serialization libraries
+  will wrap the JSON serialization libraries and replace the leading
+  '{' character with the above magic number.
+
+Object Origin: for objects intended to be mutated over time
+  (e.g. annotating and renaming a photo, commenting on an item,
+  starring something), you need a base immutable object to reference
+  when hanging other immutable objects off.  So whenever you want
+  to create a high-level mutable object, clients first create a
+  new, random dummy "Object Origin".  e.g.:
+
+  {"camliVersion":1,
+   "type":"origin",
+   "originDate":"2010-06-20T18:07:14Z",
+   "noIndexRandom":"6157669e-df09-4107-a569-c876767d2117"}
+
+  Note that the only required fields are the "camliVersion" and "type"
+  fields, identifying this object as an origin hub.  The "originDate"
+  is optional but recommended.  It says when the origin object was
+  created (but not when any of the objects it binds were created).
+  The "noIndexRandom" field simply adds randomness to the object, such
+  that the BlobRef of the object is unique, even for two objects
+  created at the exact same time by different machines.  You should
+  incorporate something specific from your machine (MAC address, IMEI,
+  etc) in your random calculation if you're not using a good
+  randomness source (e.g. using the "uuidgen" tool) The key name
+  "noIndexRandom" is not part of the spec, and it should definitely
+  not be indexed at higher levels.  It's never referenced and not
+  semantically meaningful.
+
+Object Origin Blob: the bytes of the JSON serialization of the Object
+  Origin.  As it's just a blob, it's referred to using a BlobRef.
+
+
+----------
+References
+----------
+
+[1] http://en.wikipedia.org/wiki/Magic_number_(programming)
+    http://en.wikipedia.org/wiki/File_format#Magic_number