Internal Document Model
Introduction
Cristal's internal document model is based on JSON-LD.
References
Each document or attachment has a reference.
<wiki>:<referenceonserver>
<attachment>@<wiki>:<referenceonserver>
TODO: Product team has experience with what is good and bad with references..
TODO: Open Question: should a document be a reference ?
Note: a conversion will be needed to convert a reference from Cristal to a "backend reference".
JSON-LD model
Ideally we should base the Wiki Page JSON-LD model on an existing model published on schema.org.
Most of the data in an XWiki document seems to fit in the https://schema.org/CreativeWork schema.
Basic document model
| Field | Candidate Field Name | JSON Schema | JSON Field Name | XWiki Public API | File System | GitHub/GitLab/Git | NextCloud (WebDAV or NextCloud API) | Notes |
|---|---|---|---|---|---|---|---|---|
| Notes specific to software | Metadata could be hidden as comments in Markdown file (or XWiki syntax) | Metadata could be hidden as comments in Markdown file (or XWiki syntax) https://stackoverflow.com/questions/42952149/how-to-add-metadata-in-github-flavoured-markdown | NextCloud could be viewed as a File System or as more advanced using WebDAV or NextCloud APIs | |||||
| uri/url | uri | https://schema.org/Thing | https://schema.org/url | doc.getURL | path | path | ||
| Reference | reference | https://schema.org/Thing | https://schema.org/identifier | doc.getReference() | relative path | relative path | A reference can depend on the context | |
| Name | name | https://schema.org/Thing | https://schema.org/name | doc.name | filename | filename | ||
| Title | title | https://schema.org/CreativeWork | https://schema.org/headline | doc.title | filename  | filename | ||
Parent or Breadcrumb | parentReference or breadcrumb | https://schema.org/WebPage | 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 | APIs to get the location or derive from the reference | derived from relative path | derived from relative path | ||
| Language | language | https://schema.org/CreativeWork | https://schema.org/inLanguage | doc.getLanguage() Warning: returns emply if default language. doc.getDefaultLanguage() should be called | derived from filename | derived from filename | ||
| is Translation | isTranslation | N/A | See https://schema.org/translationOfWork | doc.getLanguage()!=doc.getDefaultLanguage() | derived from filename | derived from filename | ||
| Default Language | defaultLanguage | https://schema.org/CreativeWork | see https://schema.org/translationOfWork This would point to another work (however this should be through a URL or indicating the original language not a creativeWork) | doc.getDefaultLanguage() or APIs to find the XWiki Document representing the original language
| derived from path to get the path to original language document | derived from path to get the path to original language document | This would point to another work (however this should be through a URL or indicating the original language not a creativeWork) | |
| Creation Date | creationDate | https://schema.org/CreativeWork | https://schema.org/dateCreated | doc.getCreationDate() | file system creation date or storage as metadata hidden in text document or in hidden file | creation date from git API | ||
| Update Date | lastUpdateDate | https://schema.org/CreativeWork | https://schema.org/dateModified | doc.getDate() | file system update date or storage as metadata hidden in text document or in hidden file | creation date from git API | ||
| Creator | creator | https://schema.org/CreativeWork | https://schema.org/creator | doc.getCreator() | file system creator or storage as metadata hidden in text document or in hidden file | creator from git API | ||
| Last Author | lastAuthor | https://schema.org/CreativeWork | https://schema.org/editor | doc.getUpdateDate() | file system author or storage as metadata hidden in text document or in hidden file | last author from git API | ||
| Version | version | https://schema.org/CreativeWork | https://schema.org/version | doc.getVersion() | no version or in hidden file associated to file or storage as metadata hidden in text document | version using git API (commit ID) | ||
| Syntax | syntaxId | doc.getSyntaxId() | global for the wiki or in file extension or in hidden file associated to file or storage as metadata hidden in text document | global for the wiki or in file extension or in hidden file associated to file or storage as metadata hidden in text document | ||||
| Hidden | isHidden | https://schema.org/CreativeWork | The intended audience field could be used. | doc.isHidden() | in hidden file associated to file or storage as metadata hidden in text document | in hidden file associated to file or storage as metadata hidden in text document | ||
| Content | content | https://schema.org/CreativeWork | https://schema.org/text | doc.getContent() | in file | in file | ||
| Other fields used by XWiki | ||||||||
| Edit Comment (edit comment) | comment | https://schema.org/Thing | Description could be used but could conflict with other description fields | doc.getComment() | in hidden file associated to file or storage as metadata hidden in text document | in hidden file associated to file or storage as metadata hidden in text document | ||
| Minor Edit | isMinorEdit | N/A | Could be derived from version | doc.isMinorEdit() | in hidden file associated to file or storage as metadata hidden in text document | in hidden file associated to file or storage as metadata hidden in text document | ||
| Comments | XWiki.XWikiComments class | https://schema.org/CreativeWork | https://schema.org/comment | doc.getComments() or doc.getObjects("XWiki.XWikiComments") | in separate file | in separate file | 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 . | |
| Attachments | https://schema.org/CreativeWork | https://schema.org/MediaObject | doc.getAttachments() | in separate file | in separate file | 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 . | ||
| Tags | XWiki.TagClass | https://schema.org/CreativeWork | https://schema.org/keywords | doc.getTags() or doc.getObjects("XWiki.TagClass") | in hidden file associated to file or storage as metadata hidden in text document | in hidden file associated to file or storage as metadata hidden in text document | ||
| Revisions | same model | doc.getRevisions doc.getDocumentRevisions | in separate files | in git | 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 . | |||
| Likes | Solr storage | like API | like count in hidden file or as metadata hidden in text document in separate files | like count in hidden file or as metadata hidden in text document in separate files | 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 . | |||
| Rights | XWiki.XWikiRights XWiki.XWikiGlobalRights | This probably needs it's own specific schema which can be mapped to the rights system of the underlying backends. This should only be necessary for viewing/editing rights | doc.getObjects("XWiki.XWikiRights") doc.getObjects("XWiki.XWikiGlobalRights") or simplified rights API | N/A or in separate files or in JSON-LD format in document | N/A or in separate files or in JSON-LD format in document | NextCloud will have it's own way of storing rights | 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 . | |
| Class | This probably needs it's own specific schema or use the ontology system to map the XWiki Class system to ontologies | doc.getXWikiClass() | in JSON-LD file format or in XWiki Class format | in JSON-LD file format or in XWiki Class format | in JSON-LD file format or in XWiki Class format | |||
| FullName | Derived from reference | doc.getFullName() | derived from path | derived from path | derived from path | |||
| Web/Space | Should not be used anymore | doc.getWeb() | Should not be used anymore | Should not be used anymore | ||||
Documents with Objects
General Case
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.
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
XWiki Users
The XWiki Users schema would map its fields to the Person schema: https://schema.org/Person
Blog Articles
The Blog articles would map the extra fields to the NewsArticle schema: https://schema.org/NewsArticle
Internal API
- exists(reference)
- Document getDocument(reference) - Document will correspond to the fields available in the model
- doc.save()
- doc.listAttachment() or doc.attachment.list()
- doc.getAttachment() or doc.attachment.get(filename)
- attachment.save()
- doc.getComments() or doc.comment.list()
- doc.addComment(comment) or doc.comment.add(Comment)
- doc.updateComment(comment) or doc.comment.update(Comment) or Comment.update(...)
- doc.getTags() or doc.tags.list()
- doc.getLikes() or doc.likes.list()
- doc.renameDocument(reference, newtitle, newreference)
- doc.copyDocument(reference, newtitle, newreference)
- query (similar to xwiki query API with multiple APIs)
