connectr	data store spec DRAFT

See also bug #515531

The data store is a collection of items.

Each item consists of:

• body
• possibly other things (signatures, envelope, etc)

The body is a string in JSON format; it is constant and its hash identifies the item. It contains a JSON object, with fields as per the following table (plus additional ones depending on the type).

field	type	description	default
type	string	The type of the item, eg. "status", "deleted", etc. This defines what additional fields are valid, apart from those in this table. Unknown types MUST be accepted, as future versions will expand the list; they may be discarded or stored-and-forwarded as seems best (but otherwise should probably be ignored).	(no default; mandatory)
??? supersedes	array of strings	List of hashes that this item supersedes.	empty list
??? name? id? piece?	string, maybe anything?	If this field is the same for two items (of the same type?), the newer one supersedes the older one. Who can do this? Only the original author, or also some others?	(unique)
references	array of strings	List of hashes that this item references (ie items which should really travel with this one). For a comment this would be the item on which it's commenting; for a photo tag, this would be the person tagged and the photo (two items); for a relationship status, it'd be the two persons; etc.
time	number	When the item was created.

The following types are currently defined:

type	fields	description
status	text	Status update; the "text" field stores the plain text of the update.
??? deleted	-	How to think of it? One of two ways: Does nothing; its purpose is to supersede other items. Deletes existing item(s).

Questions:

• JSON or something else? Probably JSON.
  
• Which hash?
• Do we need some sort of version ID, or is it enough that all the bodies will start with '{' ?
• Is the "supersedes" property transitive? If yes, we'll need to store and forward the superseded items, otherwise the chain will be broken; if no, each item will have to have all its predecessors listed in "supersedes".
• It probably shouldn't be transitive, so that a deletion can be retracted, and items that need to be superseded regularly should have another mechanism — some indication that when two items match on particular fields, the older one is automatically superseded. (At that point, should the field be called "supersedes" or should it be used only for deletion?)
• Who can delete an item? In some cases, could be several people (eg, either person can delete a relationship; a photo tag can be deleted by tagger, photo owner or taggee)
• What happens with items like events, where the host should be able to edit details even after others have RSVP'd, commented on or otherwise responded to the event? Should an event be a more-or-less empty shell, with the actual text of the event being supplied by subsidiary items? What fields ought to be fixed, what ought to be alterable? Or should it be that if the event is to be edited, attendees have to re-RSVP (possibly semi-automatically), and the mechanism is effectively a cancel-and-reschedule?
  

Notes:

• Should I use json.dumps(..., ensure_ascii=False) or ensure_ascii=True ? The latter former will return non-ascii characters as unicode (for encoding as utf-8), the latter will encode non-ascii characters using json escapes. Probably ensure_ascii=False.