Skip to Content

Wiki source code of Internal Document Model

Last modified by Ludovic Dubost on 2023/10/16 11:17
Show last authors
1 == Introduction ==
2
3 Cristal's internal document model is based on JSON-LD.
4
5
6 == References ==
7
8 Each document or attachment has a reference.
9
10
11 <wiki>:<referenceonserver>
12
13 <attachment>@<wiki>:<referenceonserver>
14
15
16
17 TODO: Product team has experience with what is good and bad with references..
18
19 TODO: Open Question: should a document be a reference ?
20
21 Note: a conversion will be needed to convert a reference from Cristal to a "backend reference".
22
23
24 == JSON-LD model ==
25
26 Ideally we should base the Wiki Page JSON-LD model on an existing model published on schema.org.
27 Most of the data in an XWiki document seems to fit in the [[https:~~/~~/schema.org/CreativeWork>>https://schema.org/CreativeWork]] schema.
28
29 === Basic document model ===
30
31 (% style="width:1649px" %)
32 |= Field |= Candidate Field Name |=JSON Schema|=(% style="width: 436px;" %) JSON Field Name|=(% style="width: 274px;" %) XWiki Public API|=(% style="width: 207px;" %)File System |=(% style="width: 127px;" %)GitHub/GitLab/Git|=(% style="width: 117px;" %) NextCloud (WebDAV or NextCloud API)|=(% style="width: 190px;" %) Notes
33 |=(% scope="col" %)Notes specific to software|= |= |=(% style="width: 436px;" %) |=(% style="width: 274px;" %) |=(% style="width: 207px;" %)Metadata could be hidden as comments in Markdown file (or XWiki syntax)|=(% style="width: 127px;" %)(((
34 Metadata could be hidden as comments in Markdown file (or XWiki syntax)
35
36 [[https:~~/~~/stackoverflow.com/questions/42952149/how-to-add-metadata-in-github-flavoured-markdown>>https://stackoverflow.com/questions/42952149/how-to-add-metadata-in-github-flavoured-markdown]]
37 )))|=(% style="width: 117px;" %)NextCloud could be viewed as a File System or as more advanced using WebDAV or NextCloud APIs|=(% style="width: 190px;" %)
38 |= uri/url | uri |[[https:~~/~~/schema.org/Thing>>https://schema.org/Thing]]|(% style="width:436px" %)[[https:~~/~~/schema.org/url>>https://schema.org/url]]|(% style="width:274px" %)doc.getURL|(% style="width:207px" %)path|(% style="width:127px" %)path|(% style="width:117px" %) |(% style="width:190px" %)
39 |= Reference | reference |[[https:~~/~~/schema.org/Thing>>https://schema.org/Thing]]|(% style="width:436px" %)[[https:~~/~~/schema.org/identifier>>https://schema.org/identifier]]|(% style="width:274px" %)(((
40 doc.getReference()
41 )))|(% style="width:207px" %)relative path|(% style="width:127px" %)relative path|(% style="width:117px" %) |(% style="width:190px" %)A reference can depend on the context
42 |= Name | name |[[https:~~/~~/schema.org/Thing>>https://schema.org/Thing]]|(% style="width:436px" %)[[https:~~/~~/schema.org/name>>https://schema.org/name]]|(% style="width:274px" %)doc.name|(% style="width:207px" %)filename|(% style="width:127px" %)filename|(% style="width:117px" %) |(% style="width:190px" %)
43 |= Title | title |[[https:~~/~~/schema.org/CreativeWork>>https://schema.org/CreativeWork]]|(% style="width:436px" %)[[https:~~/~~/schema.org/headline>>https://schema.org/headline]]|(% style="width:274px" %)doc.title|(% style="width:207px" %)filename (?)|(% style="width:127px" %)filename (?)|(% style="width:117px" %) |(% style="width:190px" %)
44 |=(((
45 Parent
46
47 or
48
49 Breadcrumb
50 )))|(((
51 parentReference
52
53 or
54
55 breadcrumb
56 )))|[[https:~~/~~/schema.org/WebPage>>https://schema.org/WebPage]]|(% style="width:436px" %)(((
57 This might be a bit too much to just hold the parent. However it might be better to hold the whole breadcrumb which is necessary for rendering the breadcrumb in the UI
58
59 [[https:~~/~~/schema.org/breadcrumb>>https://schema.org/breadcrumb]]
60 )))|(% style="width:274px" %)APIs to get the location or derive from the reference|(% style="width:207px" %)derived from relative path|(% style="width:127px" %)derived from relative path|(% style="width:117px" %) |(% style="width:190px" %)
61 |= Language | language |[[https:~~/~~/schema.org/CreativeWork>>https://schema.org/CreativeWork]]|(% style="width:436px" %)[[https:~~/~~/schema.org/inLanguage>>https://schema.org/inLanguage]]|(% style="width:274px" %)(((
62 doc.getLanguage()
63
64 Warning: returns emply if default language. doc.getDefaultLanguage() should be called
65 )))|(% style="width:207px" %)derived from filename|(% style="width:127px" %)derived from filename|(% style="width:117px" %) |(% style="width:190px" %)
66 |= is Translation | isTranslation |N/A|(% style="width:436px" %)See [[https:~~/~~/schema.org/translationOfWork>>https://schema.org/translationOfWork]]|(% style="width:274px" %)doc.getLanguage()~!=doc.getDefaultLanguage()|(% style="width:207px" %)derived from filename|(% style="width:127px" %)derived from filename|(% style="width:117px" %) |(% style="width:190px" %)
67 |= Default Language | defaultLanguage |[[https:~~/~~/schema.org/CreativeWork>>https://schema.org/CreativeWork]]|(% style="width:436px" %)(((
68 see
69
70 [[https:~~/~~/schema.org/translationOfWork>>https://schema.org/translationOfWork]]
71
72 This would point to another work (however this should be through a URL or indicating the original language not a creativeWork)
73 )))|(% style="width:274px" %)(((
74 doc.getDefaultLanguage()
75
76 or APIs to find the XWiki Document representing the original language
77
78
79 )))|(% style="width:207px" %)derived from path to get the path to original language document|(% style="width:127px" %)derived from path to get the path to original language document|(% style="width:117px" %) |(% style="width:190px" %)This would point to another work (however this should be through a URL or indicating the original language not a creativeWork)
80 |= Creation Date | creationDate |[[https:~~/~~/schema.org/CreativeWork>>https://schema.org/CreativeWork]]|(% style="width:436px" %)[[https:~~/~~/schema.org/dateCreated>>https://schema.org/dateCreated]]|(% style="width:274px" %)doc.getCreationDate()|(% style="width:207px" %)(((
81 file system creation date
82
83 or storage as metadata hidden in text document or in hidden file
84 )))|(% style="width:127px" %)creation date from git API|(% style="width:117px" %) |(% style="width:190px" %)
85 |= Update Date | lastUpdateDate |[[https:~~/~~/schema.org/CreativeWork>>https://schema.org/CreativeWork]]|(% style="width:436px" %)[[https:~~/~~/schema.org/dateModified>>https://schema.org/dateModified]]|(% style="width:274px" %)doc.getDate()|(% style="width:207px" %)(((
86 file system update date
87
88 or storage as metadata hidden in text document or in hidden file
89 )))|(% style="width:127px" %)creation date from git API|(% style="width:117px" %) |(% style="width:190px" %)
90 |= Creator | creator |[[https:~~/~~/schema.org/CreativeWork>>https://schema.org/CreativeWork]]|(% style="width:436px" %)[[https:~~/~~/schema.org/creator>>https://schema.org/creator]]|(% style="width:274px" %)doc.getCreator()|(% style="width:207px" %)(((
91 file system creator
92
93 or storage as metadata hidden in text document or in hidden file
94 )))|(% style="width:127px" %)creator from git API|(% style="width:117px" %) |(% style="width:190px" %)
95 |= Last Author | lastAuthor |[[https:~~/~~/schema.org/CreativeWork>>https://schema.org/CreativeWork]]|(% style="width:436px" %)[[https:~~/~~/schema.org/editor>>https://schema.org/editor]]|(% style="width:274px" %)doc.getUpdateDate()|(% style="width:207px" %)(((
96 file system author
97
98 or storage as metadata hidden in text document or in hidden file
99 )))|(% style="width:127px" %)last author from git API|(% style="width:117px" %) |(% style="width:190px" %)
100 |= Version | version |[[https:~~/~~/schema.org/CreativeWork>>https://schema.org/CreativeWork]]|(% style="width:436px" %)[[https:~~/~~/schema.org/version>>https://schema.org/version]]|(% style="width:274px" %)doc.getVersion()|(% style="width:207px" %)(((
101 no version
102
103 or
104
105 in hidden file associated to file
106
107 or
108
109 storage as metadata hidden in text document
110 )))|(% style="width:127px" %)version using git API (commit ID)|(% style="width:117px" %) |(% style="width:190px" %)
111 |= Syntax | syntaxId |(((
112 [[https:~~/~~/schema.org/CreativeWork>>https://schema.org/CreativeWork]]
113
114 [[https:~~/~~/schema.org/Thing>>https://schema.org/Thing]]
115 )))|(% style="width:436px" %)(((
116 The encoding format could be used
117
118 [[https:~~/~~/schema.org/encodingFormat>>https://schema.org/encodingFormat]]
119
120 or
121
122 [[https:~~/~~/schema.org/additionalType>>https://schema.org/additionalType]]
123 )))|(% style="width:274px" %)doc.getSyntaxId()|(% style="width:207px" %)(((
124 global for the wiki
125
126 or
127
128 in file extension
129
130 or
131
132 in hidden file associated to file
133
134 or
135
136 storage as metadata hidden in text document
137 )))|(% style="width:127px" %)(((
138 global for the wiki
139
140 or
141
142 in file extension
143
144 or
145
146 in hidden file associated to file
147
148 or
149
150 storage as metadata hidden in text document
151 )))|(% style="width:117px" %) |(% style="width:190px" %)
152 |= Hidden | isHidden |[[https:~~/~~/schema.org/CreativeWork>>https://schema.org/CreativeWork]]|(% style="width:436px" %)(((
153 The intended audience field could be used.
154
155 [[https:~~/~~/schema.org/audience>>https://schema.org/audience]]
156 )))|(% style="width:274px" %)doc.isHidden()|(% style="width:207px" %)(((
157 in hidden file associated to file
158
159 or
160
161 storage as metadata hidden in text document
162 )))|(% style="width:127px" %)(((
163 in hidden file associated to file
164
165 or
166
167 storage as metadata hidden in text document
168 )))|(% style="width:117px" %) |(% style="width:190px" %)
169 |= Content | content |[[https:~~/~~/schema.org/CreativeWork>>https://schema.org/CreativeWork]]|(% style="width:436px" %)[[https:~~/~~/schema.org/text>>https://schema.org/text]]|(% style="width:274px" %)doc.getContent()|(% style="width:207px" %)in file|(% style="width:127px" %)in file|(% style="width:117px" %) |(% style="width:190px" %)
170 |=(% colspan="8" style="text-align: center; width: 1456px;" %) Other fields used by XWiki |(% style="width:190px" %)
171 |= Edit Comment (edit comment)|comment|[[https:~~/~~/schema.org/Thing>>https://schema.org/Thing]]|(% style="width:436px" %)(((
172 Description could be used but could conflict with other description fields
173
174 [[https:~~/~~/schema.org/description>>https://schema.org/description]]
175 )))|(% style="width:274px" %)doc.getComment()|(% style="width:207px" %)(((
176 in hidden file associated to file
177
178 or
179
180 storage as metadata hidden in text document
181 )))|(% style="width:127px" %)(((
182 in hidden file associated to file
183
184 or
185
186 storage as metadata hidden in text document
187 )))|(% style="width:117px" %) |(% style="width:190px" %)
188 |= Minor Edit |isMinorEdit|N/A|(% style="width:436px" %)Could be derived from version|(% style="width:274px" %)doc.isMinorEdit()|(% style="width:207px" %)(((
189 in hidden file associated to file
190
191 or
192
193 storage as metadata hidden in text document
194 )))|(% style="width:127px" %)(((
195 in hidden file associated to file
196
197 or
198
199 storage as metadata hidden in text document
200 )))|(% style="width:117px" %) |(% style="width:190px" %)
201 |= Comments|XWiki.XWikiComments class|[[https:~~/~~/schema.org/CreativeWork>>https://schema.org/CreativeWork]]|(% style="width:436px" %)[[https:~~/~~/schema.org/comment>>https://schema.org/comment]]|(% style="width:274px" %)(((
202 doc.getComments()
203
204 or
205
206 doc.getObjects("XWiki.XWikiComments")
207 )))|(% style="width:207px" %)in separate file|(% style="width:127px" %)in separate file|(% style="width:117px" %) |(% style="width:190px" %)(((
208 For FS based storage system, a specific path to store comments will be necessary which does not overlap with usual path of documents. This could be made using files starting with .
209 )))
210 |= Attachments| |[[https:~~/~~/schema.org/CreativeWork>>https://schema.org/CreativeWork]]|(% style="width:436px" %)[[https:~~/~~/schema.org/MediaObject>>https://schema.org/MediaObject]]|(% style="width:274px" %)doc.getAttachments()|(% style="width:207px" %)in separate file|(% style="width:127px" %)in separate file|(% style="width:117px" %) |(% style="width:190px" %)For FS based storage system, a specific path to store attachments will be necessary which does not overlap with usual path of documents. This could be made using files starting with .
211 |= Tags|XWiki.TagClass|[[https:~~/~~/schema.org/CreativeWork>>https://schema.org/CreativeWork]]|(% style="width:436px" %)[[https:~~/~~/schema.org/keywords>>https://schema.org/keywords]]|(% style="width:274px" %)(((
212 doc.getTags()
213
214 or
215
216 doc.getObjects("XWiki.TagClass")
217 )))|(% style="width:207px" %)(((
218 in hidden file associated to file
219
220 or
221
222 storage as metadata hidden in text document
223 )))|(% style="width:127px" %)(((
224 in hidden file associated to file
225
226 or
227
228 storage as metadata hidden in text document
229 )))|(% style="width:117px" %) |(% style="width:190px" %)
230 |= Revisions|same model| |(% style="width:436px" %) |(% style="width:274px" %)(((
231 doc.getRevisions
232
233 doc.getDocumentRevisions
234 )))|(% style="width:207px" %)in separate files|(% style="width:127px" %)in git|(% style="width:117px" %) |(% style="width:190px" %)For FS based storage system, a specific path to store revisions will be necessary which does not overlap with usual path of documents. This could be made using files starting with .
235 |= Likes|Solr storage| |(% style="width:436px" %) |(% style="width:274px" %)like API|(% style="width:207px" %)(((
236 like count in hidden file or as metadata hidden in text document
237
238 in separate files
239 )))|(% style="width:127px" %)(((
240 like count in hidden file or as metadata hidden in text document
241
242 in separate files
243 )))|(% style="width:117px" %) |(% style="width:190px" %)For FS based storage system, a specific path to store likes will be necessary which does not overlap with usual path of documents. This could be made using files starting with .
244 |= Rights|(((
245 XWiki.XWikiRights
246
247 XWiki.XWikiGlobalRights
248 )))| |(% style="width:436px" %)(((
249 This probably needs it's own specific schema which can be mapped to the rights system of the underlying backends.
250
251 This should only be necessary for viewing/editing rights
252 )))|(% style="width:274px" %)(((
253 doc.getObjects("XWiki.XWikiRights")
254
255 doc.getObjects("XWiki.XWikiGlobalRights")
256
257 or simplified rights API
258 )))|(% style="width:207px" %)(((
259 N/A or in separate files
260
261 or in JSON-LD format in document
262 )))|(% style="width:127px" %)(((
263 N/A or in separate files
264
265 or in JSON-LD format in document
266 )))|(% style="width:117px" %)NextCloud will have it's own way of storing rights|(% style="width:190px" %)For FS based storage system, a specific path to store rights will be necessary which does not overlap with usual path of documents. This could be made using files starting with .
267 |= Class | | |(% style="width:436px" %)This probably needs it's own specific schema or use the ontology system to map the XWiki Class system to ontologies|(% style="width:274px" %)doc.getXWikiClass()|(% style="width:207px" %)in JSON-LD file format or in XWiki Class format|(% style="width:127px" %)in JSON-LD file format or in XWiki Class format|(% style="width:117px" %)in JSON-LD file format or in XWiki Class format|(% style="width:190px" %)
268 |= FullName | | |(% style="width:436px" %)Derived from reference|(% style="width:274px" %)doc.getFullName()|(% style="width:207px" %)derived from path|(% style="width:127px" %)derived from path|(% style="width:117px" %)derived from path|(% style="width:190px" %)
269 |= Web/Space | | |(% style="width:436px" %)Should not be used anymore|(% style="width:274px" %)doc.getWeb()|(% style="width:207px" %)Should not be used anymore|(% style="width:127px" %)Should not be used anymore|(% style="width:117px" %) |(% style="width:190px" %)
270
271 == Documents with Objects ==
272
273 === General Case ===
274
275 Each XWiki class should be a schema according to JSON-LD, allowing any XWiki Objects to be expressed as JSON-LD referring to the XWiki Class expressed as a JSON-LD.
276
277 Additionally each class could define some mapping for their fields to known schema.org schemas and fields. For example an XWiki.XWikiUsers class representing a user would map its fields to the Person schema [[https:~~/~~/schema.org/Person>>https://schema.org/Person]]
278
279 === XWiki Users ===
280
281 The XWiki Users schema would map its fields to the Person schema: [[https:~~/~~/schema.org/Person>>https://schema.org/Person]]
282
283 === Blog Articles ===
284
285 The Blog articles would map the extra fields to the NewsArticle schema: [[https:~~/~~/schema.org/NewsArticle>>https://schema.org/NewsArticle]]
286
287
288 == Internal API ==
289
290 * exists(reference)
291 * Document getDocument(reference) - Document will correspond to the fields available in the model
292 * doc.save()
293 * doc.listAttachment() or doc.attachment.list()
294 * doc.getAttachment() or doc.attachment.get(filename)
295 * attachment.save()
296 * doc.getComments() or doc.comment.list()
297 * doc.addComment(comment) or doc.comment.add(Comment)
298 * doc.updateComment(comment) or doc.comment.update(Comment) or Comment.update(...)
299 * doc.getTags() or doc.tags.list()
300 * doc.getLikes() or doc.likes.list()
301 * doc.renameDocument(reference, newtitle, newreference)
302 * doc.copyDocument(reference, newtitle, newreference)
303 * query (similar to xwiki query API with multiple APIs)

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected