mirror of https://github.com/perkeep/perkeep.git
71 lines
3.0 KiB
Plaintext
71 lines
3.0 KiB
Plaintext
|
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
|