diff --git a/formats/about/SPEC_1.0.md b/formats/about/SPEC_1.0.md index f2edb5a..ceaad1b 100644 --- a/formats/about/SPEC_1.0.md +++ b/formats/about/SPEC_1.0.md @@ -39,7 +39,7 @@ at any time, and which can differ between each share. The path format of a display name document is: ``` -`/about/1.0/~{KEYPAIR_ADDRESS}/displayName +/about/1.0/~{KEYPAIR_ADDRESS}/displayName ``` ### Display name document fields diff --git a/formats/sequence/SPEC_1.0.md b/formats/sequence/SPEC_1.0.md new file mode 100644 index 0000000..0c445db --- /dev/null +++ b/formats/sequence/SPEC_1.0.md @@ -0,0 +1,192 @@ +# Sequence format + +
+
Namespace
`sequence`
+
Version
1.0
+
+ +The sequence format is for storing chronologically sorted data entries. Some +common uses for this data structure include chatrooms, diaries, or microblogs. +This format is designed to be generic so as to accommodate many different +use-cases, and provides a recommended way to extend the format with additional +data. + +## Overview + +This format allows a single share to hold many named sequences, each of which +holds many chronologically ordered entries. + +Each entry belongs to a single author. The entry may or may not have an +attachment. An entry may or may not be ephemeral and be deleted after a certain +time. + +## Sequences + +A share may have many sequences, e.g: + +``` ++personalstuff.bxxx + My Journal + Dream Diary + Tasty things I ate lately +``` + +Each of these sequences is identified by a numerical ID: + +``` ++personalstuff.bxxx + [0] My Journal + [1] Dream Diary + [2] Tasty things I ate lately +``` + +This sequence ID is used in the paths of the different documents which belong to +a sequence: + +- A sequence entry document +- A sequence name document +- A sequence extension document + +All of which have paths prefixed with the following: + +`/sequence/1.0/{SEQUENCE_ID}/` + +Where `{SEQUENCE_ID}` is the numerical ID of the sequence, e.g. `2`. + +As sequence IDs only ever appear in the paths of sequence documents, a +sequence's existence is dependent on the existence of one of these sequence +documents. + +### Determining sequence IDs + +When creating a document for a new sequence and determining the sequence ID for +the path: + +- Use `0` in case no documents have been created for any sequences in the share. +- Determine the existing sequence ID with the highest numerical value, and + increment it by 1. + +The second option should be followed even if all the documents referring to the +highest sequence ID are empty (indicating deletion). + +## Sequence names + +Each sequence may optionally have a human-readable name associated with it. + +If a sequence does not have a document describing a human-readable name, clients +may choose to fall back to some other value (e.g. `Sequence 3`). + +### Sequence name document path + +The path form of a sequence name document is: + +``` +/sequence/1.0/{SEQUENCE_ID}/name +``` + +Where `{SEQUENCE_ID}` is replaced with the ID of the sequence that should have +this name. + +### Sequence name document fields + +The `text` field of the document is the desired human-readable name of the +sequence. It can be any UTF-8 string. + +If the value of the `text` field is an empty string, the document should be +treated the same way as if it were not there at all. + +## Sequence entries + +A sequence is made up of many entries, each belonging to a single author. +Entries can be overwritten or wiped, have an optional attachment, or may be +ephemeral and deleted after a certain time. + +### Sequence entry path + +The path format for an entry without an attachment is: + +``` +/sequence/1.0/{SEQUENCE_ID}/{TIMESTAMP}~{AUTHOR_ADDRESS} +``` + +Where `{SEQUENCE_ID}` is the numerical ID of the sequence this entry belongs to, +`{TIMESTAMP}` is the number of milliseconds elapsed since the UNIX epoch, and +`{AUTHOR_ADDRESS}` is the public address of the keypair which was used to sign +this document. + +The path format for a non-ephemeral entry **with** an attachment is: + +``` +/sequence/1.0/{SEQUENCE_ID}/{TIMESTAMP}~{AUTHOR_ADDRESS}.{ATTACHMENT_EXTENSION} +``` + +This is the same as before, but is suffixed with `.{ATTACHMENT_EXTENSION}`, +where `{ATTACHMENT_EXTENSION}` is the appropriate file extension for the media +type of the attached data. + +An ephemeral sequence entry document must place a `!` before the timestamp +portion of the path: + +``` +/sequence/1.0/{SEQUENCE_ID}/{TIMESTAMP}~{AUTHOR_ADDRESS} +/sequence/1.0/{SEQUENCE_ID}/!{TIMESTAMP}~{AUTHOR_ADDRESS}.{ATTACHMENT_EXTENSION} +``` + +The `TIMESTAMP` portion of the path serves two purposes: to help order the +documents chronologically, and to act as a 'created at' timestamp that persists +over subsequent edits. + +The `AUTHOR_ADDRESS` portion is prefixed with a tilde, indicating to Earthstar +that the document at this path can only be written to by the author possessing +the keypair with that address. + +### Sequence entry fields + +- The `text` property of the document is the content of the entry. It can be any + UTF-8 string. + - If the value of the `text` field is an empty string, the document should be + treated the same way as if it were not there at all. +- A sequence entry may optionally have an attachment, which can be a file of any + type. +- If the entry is ephemeral, the `deleteAfter` field must be desired expiry time + in UNIX microseconds. + +## Extension documents + +It is often desirable to associate extra attributes with a sequence and its +entries. + +For example, a sequence could be used to save memorable quotes of a child, where +each entry was a different quote. In our example we wish to extend the sequence +format so that a client application could display the current age of the child +when each quote was said. To do this, the client would need to know the child's +birthday. + +To create our extension, we would create a document at the following path: + +``` +sequence/1.0/37/ext/kid-quote/birthday +``` + +And the document would have the value of the `text` field set to something like +`2020-01-01`. Our client now has the birthday it needs to determine the age of +the child when the entry was created. + +### Sequence extension path + +The path format for a sequence extension document is: + +``` +sequence/1.0/{SEQUENCE_ID}/ext/{EXTENSION_NAMESPACE}/** +``` + +Where `SEQUENCE_ID` is the ID of the sequence being extended, and +`EXTENSION_NAMESPACE` is a string representing the extension form (e.g. +`kid-quote`). The glob portion conveys that after this, the path format is left +to the discretion of the extension in question, and may be as simple or complex +as desired, with a single subsequent path segment or many. + +### Sequence extension fields + +The fields of a sequence extension document are not proscribed and their +requirements are left to the designer of the sequence extension.