-
Notifications
You must be signed in to change notification settings - Fork 0
/
data-structure.xml
119 lines (119 loc) · 7.44 KB
/
data-structure.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
<?xml version="1.0" encoding="UTF-8"?>
<section anchor="data-structure" title="Data structure">
<t>FOSP allows users to store structured data in objects and everything else in attachments, which each belong to an object.
The objects are all part of a tree and each user owns one such tree.
</t>
<section anchor="objects" title="Objects">
<t>We refer to the basic unit of data, that can be manipulated in the FOSP network, as an object.
An object consists of key-value pairs.
The constraints for keys and values are the ones described by the JSON specification.
Each object has by default specific key value pairs that have a special meaning, for example, the key “owner” contains the identifier of the user who created the object.
When transferring objects in messages, the object is serialized according to the JSON specification.
In the rest of the document we will refer to a key-value pair of an object either as an attribute or a field of an object.
</t>
<?rfc include="figures/object.xml"?>
<t>Each object is part of a tree of objects that belong to a user.
Therefore, each object can be addressed by an internationalized resource identifier (IRI <xref target="RFC3987" />).
The syntax for an object borrows from the IRI definition and is as follows.
<figure>
<artwork type="abnf">
<![CDATA[
resource-id = 1*iunreserved "@" ihost ipath-absolute
]]>
</artwork>
</figure>
</t>
</section>
<section anchor="data-structure-fields" title="Object attributes">
<t>Most attributes of an object have a well defined meaning.
The servers have to ensure that the content of these attributes adheres to the specification and that users do not make changes that are not allowed.
<xref target="fig-object-example" /> shows an example of an objects with all the fields described here.
Currently we define the following attributes and their values:
<list>
<t>The “owner” field is set by the server on creation of the object and contains the identifier of the user who created the object as a string.
It determines the ownership of this object and is used when enforcing access rights.
The user MUST NOT be able to set the field to a different value.
</t>
<t>The “created” field is set by the server to the date of creation of the object.
It is stored as a string, formatted according to the ISO 8601 standard and must always be in the UTC time zone.
The user MUST NOT be able to set the field to a different value.
</t>
<t>Similar the “updated” field is set to the current date each time the object is altered and is not to be set by the users directly.
It is stored just like “created”.
In the future it might be used to allow client side caching similar to ETags in HTTP.
The user MUST NOT be able to set the field to a different value.
</t>
<t>The “data” field is where the user should store the payload and may contain any valid value.
The “type” field should contain a string that describes the content type of the “data” field, similar to MIME types.
These two fields are the only fields where the user can store arbitrary data.
The server MUST allow the user to store any data in these fields.
</t>
</list>
</t>
<t>Furthermore, there are the three fields “acl”, “subscriptions” and “attachment” that contain more complex objects.
</t>
<t anchor="data-structure-fields-acl">The “acl” field stores information about access rights in form of an object.
It is read by the server to enforce access control.
<list>
<t>The acl object can have the following fields: “owner”, “users”, “groups”, “other” </t>
<t>The value of the “owner” and “other” field is a set of rights</t>
<t>A set of rights is an object where each key identifies a certain scope the right applies to, and the value is a string array of permissions.
For example, the key ”acl” means that the permissions apply to the acl field of the object.
Currently allowed values for the key are “acl”, “data”, “subscriptions“, “children“.
The permissions can be “read”, “write“ and “delete”.
They can also be prefixed with “not-“ to revoke a right, which is necessary because rights are inherited.
This will be further explained in <xref target="access-control" />.
</t>
<t>The value of the “users” and “groups” field is an object.
In these objects, each key identifies a user or a group and the related value is a set of rights.
</t>
</list>
</t>
<t>The “subscriptions” field stores information about subscriptions.
It is read by the server to determine which users have to be notified on changes to an object.
<list>
<t>It contains an object and each key is the identifier of a user.</t>
<t>The value is an object with the fields: “events” and “depth”</t>
<t>The value of “events” is an array of strings which identify an event, the value of “depth” is an integer between -1 and infinity </t>
</list>
How this field is evaluated by the server is explained in <xref target="pol-subscriptions" />.
</t>
<t>The “attachment” field is only present if this object has an attachment.
It contains an object with three fields.
<list>
<t>The “name” field contains a string with the file name.
</t>
<t>The “size” field contains the number of bytes of the attached file.
The value of this field MUST be set by the server whenever a WRITE request changes the size of the file.
The value of this field MUST NOT be set by a user.
</t>
<t>The “type” field contains a string with the mime-type of the attached file.
</t>
</list>
</t>
</section>
<section anchor="obj-trees" title="Trees">
<t>In FOSP, all objects are part of a tree of objects.
Therefore, all objects have a parent object, except for the root object of a tree.
Consequently, all objects can have child objects.
For each user there exists one tree of objects and the root node of this tree is named like the identifier of the user.
The tree of the user is stored on the servers that are responsible for the domain of the provider where the user is registered.
<?rfc include="figures/tree.xml" ?>
</t>
</section>
<section anchor="data-structure-attachments" title="Attachments">
<t>As files, like pictures and documents, are also shared via social networks, FOSP supports saving binary files.
For each object, one file can be stored as an attachment.
This way, files can be addressed with the same schema and the objects they are attached to can provide the meta-data.
If an object has a belonging file, it is extended by a new attribute named “attachment”.
In this attribute, the "size", file "name", and MIME "type" of the file is stored.
The attached file is read and written using special requests.
</t>
</section>
<section anchor="std-objs" title="Provisioned Objects">
<t>Some objects in the tree of a user will be used by the server to obtain configuration options.
For example [email protected]/config/groups will contain the mappings from users to groups that are valid for the tree [email protected].
These objects will be created by the server when the user first registers with it.
</t>
</section>
</section>