Skip to content

Commit 4becaae

Browse files
michielbdejongmichielbdejong
authored
Merge pull request #66 from solid/shapes-doc
Shapes documentation
2 parents 5a0e16d + 7cf4856 commit 4becaae

1 file changed

Lines changed: 234 additions & 0 deletions

File tree

‎Documentation/conventions.md‎

Lines changed: 234 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,234 @@
1+
# Data Conventions used by the databrowser
2+
This document describes how the databrowser stores your data as triples in RDF documents on your pod.
3+
As most Solid pods will have at least some data on them that was edited through the databrowser,
4+
these conventions are a good place to start when you develop third-party apps. In the future, we'll
5+
see how this document can grow into a bigger participatory wiki of data shape conventions for Solid.
6+
7+
For short-hand, we will use the following namespace prefixes here:
8+
9+
* @prefix ab: <http://www.w3.org/ns/pim/ab#>.
10+
* @prefix acl: <http://www.w3.org/ns/auth/acl#>.
11+
* @prefix dc: <http://purl.org/dc/elements/1.1/>.
12+
* @prefix dct: <http://purl.org/dc/terms/>.
13+
* @prefix flow: <http://www.w3.org/2005/01/wf/flow#>.
14+
* @prefix foaf: <http://xmlns.com/foaf/0.1/>.
15+
* @prefix ical: <http://www.w3.org/2002/12/cal/ical#>.
16+
* @prefix ldp: <http://www.w3.org/ns/ldp#>.
17+
* @prefix mee: <http://www.w3.org/ns/pim/meeting#>.
18+
* @prefix pim: <http://www.w3.org/ns/pim/space#>.
19+
* @prefix rdf: http://www.w3.org/2000/01/rdf-schema#>.
20+
* @prefix schema: <http://schema.org/>.
21+
* @prefix sioc: <http://rdfs.org/sioc/ns#>.
22+
* @prefix solid: <http://www.w3.org/ns/solid/terms#>.
23+
* @prefix stat <http://www.w3.org/ns/posix/stat#>.
24+
* @prefix ui: <http://www.w3.org/ns/ui#>.
25+
* @prefix vcard: <http://www.w3.org/2006/vcard/ns#>.
26+
* @prefix xsd: <http://www.w3.org/2001/XMLSchema#>.
27+
28+
One of the most important RDF documents on your pod is your profile, which is the document that people get when they dereference your webid. We'll look at that first. After that, we'll look at each of the tools that can be created with the databrowser's + button: Addressbook, Notepad, Chat, LongChat, Meeting, Event, Link, Document, Folder, and Source.
29+
30+
## Profile
31+
### Profile document
32+
To add information to your webid profile, you can use the following triples. Suppose your webid is /profile/card#me, then your profile document is /profile/card (without the '#me'). Add the following triples to it:
33+
34+
* </profile/card> a foaf:PersonalProfileDocument
35+
* </profile/card> foaf:maker </profile/card#me>
36+
* </profile/card> foaf:primaryTopic </profile/card#me>
37+
38+
### You as a person
39+
Now say your name is "John Doe", then add these triples to your profile document to publish your identity as a person:
40+
41+
* </profile/card#me> a foaf:Person
42+
* </profile/card#me> a schema:Person
43+
* </profile/card#me> foaf:name "John Doe"
44+
45+
### Linking to your pod
46+
Say your pod is at /pod, with the LDN inbox at /pod/inbox/, to link from your identity to your pod:
47+
48+
* </profile/card#me> solid:account </pod>
49+
* </profile/card#me> pim:storage </pod>
50+
* </profile/card#me> ldp:inbox </pod/inbox/>
51+
52+
### Preferences
53+
To publish some of your generic preferences to apps, use:
54+
55+
* </profile/card#me> pim:preferencesFile </settings/prefs.ttl>
56+
* </profile/card#me> solid:publicTypeIndex </settings/publicTypeIndex.ttl>
57+
* </profile/card#me> solid:privateTypeIndex </settings/privateTypeIndex.ttl>
58+
59+
## Address Book
60+
You can create an addressbook containing persons and groups, by adding triples to RDF documents on your pod.
61+
To create an addressbook, create a document for it, e.g. /address-book/index.ttl, and add the following triples to that document:
62+
63+
* </address-book/index.ttl#this> a vcard:AddressBook
64+
* </address-book/index.ttl#this> dc:title "New address Book"
65+
* </address-book/index.ttl#this> acl:owner </profile/card#me>
66+
67+
You can create separate documents for the people index and for the groups index, as long as you link to those from the main /address-book/index.ttl document in the following ways:
68+
69+
* </address-book/index.ttl#this> vcard:nameEmailIndex </address-book/peopleIndex.ttl>
70+
* </address-book/index.ttl#this> vcard:groupIndex </address-book/groupIndex.ttl>
71+
72+
To indicate that a person /johnDoe.ttl with full name "John Doe" is in addressbook /address-book/index.ttl, add the following triples:
73+
74+
* </johnDoe.ttl#this> vcard:inAddressBook /address-book/index.ttl#this (NB: needs to be in /address-book/peopleIndex.ttl)
75+
* </johnDoe.ttl#this> a vcard:Individual
76+
* </johnDoe.ttl#this> vcard:fn "John Doe"
77+
78+
To indicate that addressbook /address-book/index.ttl has a group called "Colleagues", add the following triples:
79+
80+
* </address-book/index.ttl#this> vcard:includesGroup /address-book/colleagues.ttl#this (NB: needs to be in /address-book/groupIndex.ttl)
81+
* </address-book/colleagues.ttl#this> a vcard:Group
82+
* </address-book/colleagues.ttl#this> vcard:fn "Colleagues"
83+
84+
## Notepad
85+
To create a new notepad at /notepad.ttl, add the following triples into it:
86+
87+
* </notepad.ttl#this> a pim:Notepad
88+
* </notepad.ttl#this> dc:author </profile/card#me>
89+
* </notepad.ttl#this> dc:created "2019-04-17T08:05:19Z"^^XML:dateTime
90+
* </notepad.ttl#this> dc:title "Shared Notes"
91+
92+
Now to indicate that his notepad is empty, add an empty first line to it:
93+
94+
* </notepad.ttl#this> pim:next </notepad.ttl#this_line0>
95+
* </notepad.ttl#line0> dc:author </profile/card#me>
96+
* </notepad.ttl#line0> dc:content ""
97+
98+
Now indicate that this is the last line, set this line's pim:next to the notepad itself:
99+
100+
* </notepad.ttl#line0> pim:next </notepad.ttl#this>
101+
102+
To add a line to the notepad, for instance 'first line', first update the content of the first line, by replacing
103+
104+
* </notepad.ttl#line0> dc:content ""
105+
106+
with
107+
108+
* </notepad.ttl#line0> dc:content "first line"
109+
110+
and then add a new participation-line below it, where the user can type their next line; pick a timestamp, for instance 1555488949899, and add the following triples:
111+
112+
* </notepad.ttl#this> flow:participation </notepad.ttl#id1555488949899>
113+
* </notepad.ttl#id1555488949899> flow:participant </profile/card#me>
114+
* </notepad.ttl#id1555488949899> ical:dtstart "2019-04-17T08:05:22Z"^^XML:dateTime
115+
* </notepad.ttl#id1555488949899> ui:backgroundColor "#c0d2fe"
116+
117+
Note that the first line still is the only line in the document, apart from the participation line. To add a second line, start making proper use of the pim:next attribute, by linking the first line to the second line, and then linking the second line back up to the notepad as a whole. The participation line stays as it is. The result will then look like this:
118+
119+
### Main notepad
120+
* </notepad.ttl#this> a pim:Notepad
121+
* </notepad.ttl#this> dc:author </profile/card#me>
122+
* </notepad.ttl#this> dc:created "2019-04-17T08:05:19Z"^^XML:dateTime
123+
* </notepad.ttl#this> dc:title "Shared Notes"
124+
* </notepad.ttl#this> pim:next </notepad.ttl#this_line0>
125+
* </notepad.ttl#this> flow:participation :id1555488949899
126+
127+
### Participation
128+
* </notepad.ttl#id1555488949899> flow:participant </profile/card#me>
129+
* </notepad.ttl#id1555488949899> ical:dtstart "2019-04-17T08:05:22Z"^^XML:dateTime
130+
* </notepad.ttl#id1555488949899> ui:backgroundColor "#c0d2fe"
131+
132+
### First line
133+
* </notepad.ttl#line0> dc:author </profile/card#me>
134+
* </notepad.ttl#line0> dc:content "first line"
135+
* </notepad.ttl#line0> pim:next :id1555489499814
136+
137+
### Second line
138+
* </notepad.ttl#id1555489499814> dc:author </profile/card#me>
139+
* </notepad.ttl#id1555489499814> dc:content "second line"
140+
* </notepad.ttl#id1555489499814> pim:next :</notepad.ttl#this>
141+
142+
## Chat
143+
To create a chat conversation, create a document, e.g. /chat.ttl, and add the following triples to it:
144+
145+
* </chat.ttl#this> a mee:LongChat
146+
* </chat.ttl#this> dc:author </profile/card#me>
147+
* </chat.ttl#this> dc:created "2018-07-06T21:36:04Z"^^XML:dateTime
148+
* </chat.ttl#this> dc:title "Chat channel"
149+
150+
To add a message in the chat conversation, for instance where you say "hi", generate a timestamp like 1555487418787 and add the following triples to /chat.ttl:
151+
152+
* </chat.ttl#Msg1555487418787> dct:created "2019-04-17T07:50:18Z"^^XML:dateTime
153+
* </chat.ttl#Msg1555487418787> sioc:content "hi"
154+
* </chat.ttl#Msg1555487418787> foaf:maker </profile/card#me>
155+
156+
Note that for historical reasons, for the chat conversation as a whole, we use `dc:created` and `dc:author`, whereas for the individual chat messages we use `dct:created` and `foaf:maker`.
157+
158+
## Long Chat
159+
LongChat is similar to Chat, except that it uses LDP containers to discover the triples that describe the chat conversation,
160+
instead of having all the triples in one chat.ttl doc.
161+
To create a chat conversation, pick a timestamp, e.g. 1555491215455, create an LDP container, for instance /long-chat/, and in there, create an index document, e.g. /long-chat/index.ttl. To the index document, add the following triples:
162+
163+
* </long-chat/index.ttl#this> a mee:LongChat
164+
* </long-chat/index.ttl#this> dc:author </profile/card#me>
165+
* </long-chat/index.ttl#this> dc:created "2018-07-06T21:36:04Z"^^XML:dateTime
166+
* </long-chat/index.ttl#this> dc:title "Chat channel"
167+
* </long-chat/index.ttl#this> flow:participation :id1555491215455
168+
* </long-chat/index.ttl#this> ui:sharedPreferences :SharedPreferences
169+
* </long-chat/index.ttl#id1555491215455> ic:dtstart "2019-04-17T08:53:35Z"^^XML:dateTime
170+
* </long-chat/index.ttl#id1555491215455> flow:participant </profile/card#me>
171+
* </long-chat/index.ttl#id1555491215455> ui:backgroundColor "#c0d2fe"
172+
173+
To add a message in the LongChat conversation, for instance where you say "hi", pick a filename, for instance /long-chat/2019/04/17/chat.ttl, generate a timestamp like 1555487418787 and add the following triples to /long-chat/2019/04/17/chat.ttl:
174+
175+
* </long-chat/2019/04/17/chat.ttl#Msg1555487418787> dct:created "2019-04-17T07:50:18Z"^^XML:dateTime
176+
* </long-chat/2019/04/17/chat.ttl#Msg1555487418787> sioc:content "hi"
177+
* </long-chat/2019/04/17/chat.ttl#Msg1555487418787> foaf:maker </profile/card#me>
178+
* </long-chat/index.ttl#this> flow:message </long-chat/2019/04/17/chat.ttl#Msg1555487418787>
179+
180+
Note that there is no need to make /long-chat/2019/04/17/chat.ttl discoverable from /long-chat/index.ttl, since it can be discovered by following the LDP Container member listings for /long-chat/, /long-chat/2019/, /long-chat/2019/04/, and /2019/04/17/.
181+
Also note that here too, for the chat conversation as a whole, we use `dc:created` and `dc:author`, whereas for the individual chat messages we use `dct:created` and `foaf:maker`.
182+
183+
## Meeting
184+
To create a meeting, create a document, e.g. /meeting.ttl and add the following triples to it:
185+
186+
* </meeting.ttl#this> a mee:Meeting
187+
* </meeting.ttl#this> dc:author </profile/card#me>
188+
* </meeting.ttl#this> dc:created "2018-07-06T21:36:04Z"^^XML:dateTime
189+
* </meeting.ttl#this> flow:participation :id1555491215455
190+
* </meeting.ttl#this> ui:backgroundColor "#ddddcc"^^XML:color
191+
* </meeting.ttl#this> mee:toolList ( </meeting.ttl#this> )
192+
* </meeting.ttl#id1555491215455> ic:dtstart "2019-04-17T08:53:35Z"^^XML:dateTime
193+
* </meeting.ttl#id1555491215455> flow:participant </profile/card#me>
194+
* </meeting.ttl#id1555491215455> ui:backgroundColor "#c0d2fe"
195+
196+
To add some details, pick a name like "Weekly Meeting"(note the use of `ical:summary` instead of `dc:title` here), a start and end date/time, a comment like "Discuss weekly things", and a location like "Utrecht", and add them using the ical namespace:
197+
198+
* </meeting.ttl#this> ical:summary "Weekly Meeting"
199+
* </meeting.ttl#this> ical:comment "Discuss weekly things";
200+
* </meeting.ttl#this> ical:dtstart "2019-04-19"^^XML:date;
201+
* </meeting.ttl#this> ical:dtend "2019-04-20"^^XML:date;
202+
* </meeting.ttl#this> ical:location "Utrecht";
203+
204+
To add material to the meeting (let's say https://example.com/agenda-meeting.html), pick a timestamp like 1555492506279, remove the old `mee:toolList` triple which only contained `</meeting.ttl#this>`, and add the following triples:
205+
206+
* </meeting.ttl#this> mee:toolList ( </meeting.ttl#this> </meeting.ttl#id1555492030413> ) # updated from earlier
207+
* </meeting.ttl#id1555492506279> a mee:Tool
208+
* </meeting.ttl#this> flow:attachment <https://example.com/agenda-meeting.html>
209+
* </meeting.ttl#id1555492506279> mee:target <https://example.com/agenda-meeting.html>
210+
* </meeting.ttl#id1555492506279> rdf:label "Agenda"
211+
* </meeting.ttl#id1555492506279> mee:view "iframe"
212+
213+
## Schedulable Event
214+
// TODO
215+
216+
## Link
217+
// TODO
218+
219+
## Dokieli Document
220+
A 'Dokieli Document' is an HTML document with some linked-data annotations, but otherwise just HTML. So the 'Dokieli Document' tool does not store data in triples in RDF sources like most other tools do, but instead allows you to run an online HTML editor right on your pod. When you click 'Save' in the Dokieli editor, the HTML document is written to your pod using a http PUT request, and in that sense this editor makes use of the LDP (read-write web) functionalities of your pod. You can also use Dokieli as a third-party app, on https://dokie.li.
221+
222+
## Folder
223+
When you add a 'Folder' tool, the databrowser creates a new LDP container. As an example, here are the triples that describe an LDP container '/foo/' with subcontainer '/foo/sub/' and member document '/foo/bar.ttl':
224+
* </foo/> a ldp:BasicContainer
225+
* </foo/> a ldp:Container
226+
* </foo/> a ldp:Resource
227+
* </foo/> dct:modified "2019-04-17T08:42:16Z"^^XML:dateTime
228+
* </foo/> stat:mtime 1555490536.16
229+
* </foo/> stat:size 4096
230+
* </foo/> ldp:contains </foo/sub/>
231+
* </foo/> ldp:contains </foo/bar.ttl>
232+
233+
## Source
234+
When you add a 'Source' tool to a container, it creates an empty document as an LDP resource. The content type will be guessed from the extension, for instance source.ttl will be a Turtle document, source.txt will be text/plain, etc.

0 commit comments

Comments
 (0)