Decentralised Authoring, Annotations and Notifications for a Read-Write Web with dokieli

Decentralised read-write environments make it possible for different actors (e.g., authors, reviewers) to have their own personal online storages where they can: manage their data; have socially-aware access controls on the data (e.g., who gets to see and update what); send notifications based on their interactions; and permit different applications to operate on the data, including moving the data from one server to another seamlessly.

Figure 1 depicts the contrast between typical centralised and decentralised architectures.

dokieli as a client-side application can be deployed on a single-page or through a browser extension, which can consume and interact with Linked Data (or otherwise) anywhere on the Web. We consider an HTML document with CSS and JavaScript as the default UI of a document. Through the separation of the layers, other UIs can work injunction with the same HTML. This approach is independent from specific server-side software, proprietary APIs or the requirement to have an account.

On the other hand, if desired and available, users can participate using their own profiles (WebIDs) located anywhere on the Web, and get to store and make their annotations in their own personal storage, as well as assign access controls to documents. Similarly, a decentralised communications protocol, Linked Data Notifications (LDN) – W3C Proposed Recommendation – is used get past the limits of centralisation by enabling communication to happen across independent servers and applications. Figure 2 depicts relations between the kinds of entities which underlay dokieli’s architecture, where nodes are under different domains and authority.

dokieli can self-replicate, in that the reader of a dokieli document can spawn an instance — either a copy or a brand new empty document — into their own storage space at the click of a button.

Documents use HTML5 Polyglot Markup to ensure that when served as (X)HTML respectively, they can be processed as either HTML or XML, which is useful in XML ecosystems and toolchains. Semantics is embedded directly into human-visible prose using RDFa. The machine-readable data is thus kept in context, reusing the article’s text as literal object values, and avoiding data duplication or data ‘islands’, which can occur when other RDF serialisations are included within HTML <script> elements.

The appearance of documents is determined with CSS3. Different stylesheets can be applied to the same HTML structure so that a document can be presented flexibly, in the most appropriate way for a particular circumstance. Stylesheets can be switched from either dokieli’s menu or through Web browser with native controls, for example from a two-column layout required by an academic journal to a design in keeping with the author’s blog.

When JavaScript is enabled, dokieli provides a rich editing interface which includes visual and structural formatting of text as well as embedding machine-readable semantics, media, dynamic citations, and inclusion of statistical charts from live endpoints. An external personal data store, or even internet connection, are not needed at this stage as modifications to a document made in the browser this way can be persisted to a local filesystem using the dokieli menu export function (or the browser’s save as), or through brower’s native local storage.

Documents can be retrieved from Web servers with a single HTTP GET request, by either a browser (for human-readable HTML) or script (machine-readable RDF). Through the use of progressive enhancement, document contents are available in text-only browsers, and further functionality of CSS and JavaScript are layered on according to the user agent’s abilities.

dokieli’s approach to marking human-visible content in RDFa makes it possible to further decouple itself, the application that produced the data, from the data itself, facilitating potential reuse of the data by other applications. A dokieli document can be parsed into a graph, and users can use any other RDF-aware application with the data that was generated by dokieli. Thereby, dokieli can effectively remove itself as a dependency when it comes to data consumption and reuse.

dokieli is able to authenticate users via WebID-TLS if they provide a WebID. This enables further functionality: the user can use dokieli to access protected resources and write to non-public data storage containers if their WebID is authorised to do so. For authenticated users leaving annotations on other documents dokieli fetches their name and display picture from their online profile if available, to display alongside their comment.

dokieli uses the following vocabularies as standard: schema.org to describe the general-purpose relations about the document as well as profiles, the SPAR Ontologies for scholarly articles and referencing, Web Annotations for annotations (with motivations e.g., replying, bookmarking, commenting, assessments), LDP for personal storage management, WAC/ACL for access control, LDN Inbox and ActivityStreams for social notifications, Creative Commons for rights and licensing, PROV Ontology for provenance (e.g., for derivations with save as), and the RDF Data Cube vocabulary to consume multi-dimensional data from SPARQL endpoints. Authors can optionally include other vocabularies to mark up specific concepts through dokieli’s UI.

Documents can of course be published on ordinary Web servers, as Web pages. The next layer of enhancement is for authors who wish to edit documents on a Web server directly rather than locally; they can make use of dokieli’s write operations. This uses JavaScript, and moves the burden of processing user input from servers (i.e., offering HTML forms and processing of the form submission) to the client where the payload uses the RDF language. Data shape verification is an orthogonal process and can be addressed through servers processing the payload based on the constraints advertised for the resource (e.g., via ldp:constrainedBy). In essence, dokieli behaves as a smart client.

dokieli implements the Linked Data Platform (LDP) protocol for creating, updating and deleting documents. As such, personal data stores or servers which implement the server portion of the protocol can be used to store and edit dokieli documents directly. An HTTP PUT request to a URL is used to create a new document, to clone an existing one with save as, to save changes, and so that readers of a document can create their own document in reply. All of these operations are available through the dokieli menu.

Interactions with a document with respect to Web Annotations include the following motivations: replying, describing (e.g., footnotes), commenting, assessing (e.g., approvals, disapprovals, and request for specificity used towards peer-reviews), bookmarking, and tagging. They can be about the document as a whole, or of a selection of text. In both cases, the dokieli menu presents an input to the annotator, along with a choice of license which they can assign to their contributions. dokieli then adds semantic markup based on all of the input, and then sends the data off for appropriate storage so it can be retrieved and re-displayed on future document loads. These write operation requests are made with HTTP POST.

Document authors can point to a storage service (using the Web Annotations annotationService property) which lets readers without their own personal storage comment nonetheless. Readers who have a preferred storage location against which they can authenticate are able to direct dokieli to store their input there instead (or in addition). dokieli allows users to remove their annotations, where an HTTP DELETE request is made to the server. In this way, dokieli does not impose a centralised mechanism for social interactions, and allows users to effectively ‘own’ their comments, annotations, and reviews, in their own space.

When readers interact with a document, the author is notified by means of the Linked Data Notifications (LDN) protocol. A notification, composed of the data from the interaction or annotation, is sent to the inbox advertised by the document or arbitrary parts, thereof. This inbox may be on the same server as the document itself, or may be elsewhere. dokieli subsequently reads this inbox to display interactions and annotations on the document.

Authors of documents who have write-access to its inbox can remove notifications for interactions they find inappropriate, without needing to worry about their inability to access the original source of the interaction. Similarly, if they do not have access to the inbox, they may assign an alternative inbox for the article (or its parts). Conversely, annotators do not lose control or authority over their contributions, even if the object of their interaction wishes to disassociate itself. Each contributor retains their own respective rights over the entities they create on the Web.

dokieli’s components include data (for structure and semantics), stylesheets (for presentation) and scripts (for interaction). All data (articles, annotations, notifications) are represented in HTML and RDF with vocabularies expressing the underlying content, resources are self-descriptive to increase their reuse, and contain relations to related external resources to foster follow-your-nose type of exploration.

Several stylesheets provide alternative views for consumption (e.g., stylesheets for different media: screens, print, slideshow). dokieli’s JavaScript includes: a library for editing (MediumEditor) in its authoring environment; features to fetch and display statistical data from SPARQL endpoints (Sparqlines); retrieval of profile information, as well as means to sign in with WebID Authentication over TLS; functionality for write-operations, which includes checking authorisation against access-control level settings on the server with the authenticated user’s WebID and personal certificate; creation and consumption of Web Annotations and Linked Data Notifications; and fetching information from remote articles when adding a citation.

The scope of dokieli includes documents and the interactions around them. The creation and maintenance of user profiles, personal storage spaces, and access control rules are not managed by dokieli; since they are all standard mechanisms, users are expected to be able to accomplish this using other specialised applications.

dokieli employs two complementary deployment approaches: single-page application and Web browser extension.

dokieli’s presentational and behavioural code layers can be included in Web pages in order to trigger them as active single-page applications. It is a smart client that allows different kinds of articles e.g., academic, blog posts, news, to be authored and annotated from within Web browsers, without necessarily having them deployed from a server, i.e., it can be used offline or on localhost. dokieli internally handles its content and well-formed structural and semantic representation based on user’s interactivity. Articles, profiles and their contact information, notifications, annotations with different motivations, for instance, can be read and written ubiquitously to any Web space with supporting HTTP methods and access control mechanisms.

The Web browser extension is a thin wrapper around dokieli’s core code in order to embed itself in any HTML-based Web page on the Web. It inherits all of the features of a single-page application. While HTML based documents on the Web vary in their quality, dokieli’s write operations generate well-formed HTML+RDFa. One of the primary utilities for the extension is to have a consistent interface for annotating (comment, bookmark, like) any text selection on a Web page, as well as sharing parts of pages with ones contacts via notifications, without having a service dependency or being limited by the Web page’s UI.

Screencasts for the following use-cases showcase dokieli’s social features where users interact by creating and sharing information, available at https://dokie.li/

Annotations: A core feature to facilitate collaboration is the possibility to annotate arbitrary parts of a Web document (e.g., Digital Publishing Annotation Use Cases). Users can select an entity or a span of text of interest, a context menu is presented to input their annotations along with the choice to select a license for their contribution. If the user is signed-in with their WebID, and provided they have a personal storage space, dokieli discovers this through their online profile and saves the annotations to that location. Once the annotation is submitted by the user, dokieli proceeds with three operations: 1) the annotation is requested to be saved at the user’s personal storage, and if it is access controlled, the user will be prompted to authenticate themselves against that server, before the annotation is saved and is assigned its own URL, 2) if the article or any identifiable statement or segment has its own inbox, dokieli sends a notification to the inbox indicating that an annotation was made and where its retrievable location is, with accompanying metadata like who created it, date, its license etc., 3) the annotation is fetched from its canonical location, and integrated into the article e.g., in marginalia. If the article has a reference to a public annotation service (a writeable space adhering to Web Annotation Protocol), the user has the option to send a copy of the annotation there as well. In cases where the user does not want to have the canonical copy of the annotation on their server, or if a user does not have write access to a storage, they can still use this option to engage with the article.

Social Sharing: A key aspect of the Social Web is sharing with others. After (optionally) authenticating with a WebID, dokieli documents can be shared with contacts, which are discovered from the user’s WebID profile. Contacts whose profiles advertise an LDN Inbox will receive a notification of the share. The notification contains Activity Streams 2.0 vocabulary terms, and recipients can use any LDN-compatible application to view the notification, without needing to have ever used dokieli before.

Inline Citations: Rich semantic links can also be established between dokieli documents themselves. The author selects a text fragment and inserts the URL of the document to be linked to as well as a semantic link type (e.g. agrees with, confirms, cites as evidence) from the CiTO and schema.org ontologies. dokieli automatically retrieves metadata (e.g. title, authors) from the linked document and adds a proper scientific endnote reference. If the cited article advertises its won LDN inbox, a notification of the citation is sent as well, thus allowing bi-directional linking.

Statistical Data and Diagrams: Embedding dynamically generated diagrams and charts is possible: after selecting text, the dokieli context menu offers results of a search across registered SPARQL endpoints for the keywords in the selected text, and presents a list of available data series to visualise. The result is an inline sparkline diagram.

The W3C Working Group Note Embedding Web Annotations in HTML includes examples from dokieli’s use of the Web Annotation data Model and Vocabulary with motivations for example for Lightweight, decentralised Annotation Tools. The W3C Linked Data Notifications specification uses dokieli’s HTML+RDFa template, and the Editor’s Draft showcase dokieli as a consumer of LDN and Web Annotations. The LDN test suite also uses dokieli’s templates and stylesheets.

The academic workshop SemStats series use dokieli in its Website templates, including the call for contributions. CEUR-WS.org, an Online Proceedings for Scientific Conferences and Workshops offers the tooling ceur-make to help organisers generate proceedings using dokieli’s HTML+RDFa template, e.g., SemStats 2016. We list a community (of academics) who self-publish their articles and thesis using dokieli with different stylesheets and derived scripts under its examples in the wild. The conference series: WWW (e.g., LDOW and WOW workshops), ISWC, and ESWC propose dokieli as one tooling in which authors can use to make their contributions to the calls with.

The Linked Research website uses dokieli in its templates on the site as well as workshop proposals and call for contributions. csarven.ca uses dokieli in full, where some articles (like this article) offer pointers to a public annotation service in which users may wish to use for their annotations. Articles also dynamically embed annotations from personal storage spaces.