Knowledge Ring Application
 | Creates and display a network of pages connected by relations. Not to be installed directly with the Extension Manager, please refer to the installation notes. |
| Type | XAR |
| Category | Application |
| Developed by | Clément Aubin, Anca Luca, slauriere |
| Active Installs | 2 |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
| Compatibility | Requires XWiki 11.10. |
Table of contents
Description
The Ring application allows to draw relations between wiki pages. For instance, the relation has author can be created to state that page The Jungle Book has relation has author with page Rudyard Kipling. Relations are stored in the wiki as any other page, with the only specificity that they have relation is a with the page Relation. Each page connections can be browsed using a widget showing up under their title, allowing also to add new connections.
The application allows to:
- Create relations and types as wiki pages
- Use these relations to interlink pages with one another, hence creating "rings": a ring joins a page, a relation and another page. In addition, a ring can have internal properties.
- Explore pages via their relations, using facets.
- Define relations constraints and properties.
A ring is an ordered tuple consisting of:
- A referent page
- A relation
- A target page or a scalar value (string, date, number, etc.),
- A set of properties
For example, The Jungle Book has author Rudyard Kipling or The Jungle Book has publication date 1894 are rings.
Relations can have specific constraints, such as a constraint about the pages they can bind to one another. For instance, the relation has author will typically accept as target pages only those of type person or organization. A page type is defined by linking it to the built-in Type page via relation is a, built-in as well. For example: Book is a Type.
Representation of a graph. Source: Textgraphs.org
User interface
Once installed, the application adds a block to each page header which displays the list of pages that are linked with the current one. This list can be ordered by page title or by last modification date.
This block also includes crosses for removing existing rings, and a button for adding new ones. When hitting this button, a form shows up, displaying the list of relations that the current page can use, and a search input field for selecting a destination page. For instance, once the types "Person" and "Book" have been defined with appropriate constraints, on page The Jungle Book, once declared as a book, the form will typically propose the relations has author, has publication date, has publisher, etc. When selecting the relation has author, the search input field will suggest all the wiki pages of type person that match the entered input. The form supports only the addition of rings linking two pages together, not yet a page and a scalar value. For adding scalar values, the object editor has to be used.
The user interface also includes a Filter which makes it possible to restrict the list of related pages by their own types or relations. All relations available in the wiki are automatically added to the faceting system for easy navigation across the network of rings.
In order to draw a ring between two pages, the user needs to have at least edit right on the referent page. On a given page, a user will see all the related pages even whatever his access rights on them: in case he has no view access on a given connected page, he will get a denied access only when trying to view the content of that page.
Page "The Jungle Book" and its related pages
Form for connecting pages, hence drawing rings
Example: Nobel Prize laureates
The application includes a Wikidata data importer which creates a set of relations and types corresponding to Nobel Prizes Laureates data – in particular the relations has award, has country, and the types person and organization – and import data into the wiki.
Wikidata is a project that stores data using a graph structure, and provides interfaces for browsing the graph visually and for entering new statements.
Once imported into the wiki, the Nobel Prize laureate pages can be browsed using facets. For instance, all organizations and persons who received the Nobel Peace Prize can be browsed by country.
Facet filtering on page "Person"
Data model
| Concept | Definition | |
|---|---|---|
| Term | A Term simply wraps a wiki page. It can have inward and outward rings. | |
| Ring | A a ring typically links together two terms – a referent and a destination (also known as relatum) – via a relation. The Jungle Book has author Rudyard Kipling is a ring whose referent / relation / relatum are respectively The Jungle Book, has author, Rudyard Kipling. A ring can itself be a term, so that in the future it will also be possible to create rings involving rings, such as: Anna says that "The Jungle Book has author Rudyard Kipling", where says is a relation used by the ring having referent Anna and relatum The Jungle Book has author Rudyard Kipling. For now this type of statement can be represented via ring properties. | |
| Relation | A relation has a domain and an image. Its domain is the set of terms on which it can be applied to, and its image is the set of terms it can accept as values. For instance, has award is a relation whose domain is the set of pages representing a person or an organization and whose image is the set of pages that represent an award. | |
| RRing | A RRing is a set of terms, rings or relations. |
Ring application class diagram
Built-in relations
The application includes a set of predefined relations described below, and one type.
| Relation or Type | Description | Example |
|---|---|---|
| Is connected to | Can be used to express that two pages are related to one another. | The Jungle Book is connected to Rikki-Tikki-Tavi. |
| Is a | Can be used to declare that a page has a specific type. | Rudyard Kipling is a person. |
| Is transitive | Can be used to specify whether a relation is transitive or not. | Relation is a is transitive: if Rudyard Kipling is a journalist, and journalist is a person, then Rudyard Kipling is a person. This property is not used by the application at the moment. |
| Has domain | Can be used to specify the set of pages a relation can have as referents. It is similar to the RDF schema domain property, except that rdfs:domain only accept class names, while the has domain relation can accept any set definition. | Relation has head office has domain organization. |
| Has image | Can be used to specify the set of pages a relation can have as relatum. It is similar to the RDF schema range property. The terms domain and image come from the mathematical definition of a relation. | Relation has author has image person. |
| Type | Represents a type. | The page Type has relation is a with itself: a type is a type. Book is a type. |
Visual representation of an example set of terms, relations and rings. Rings are circles connecting an origin, a relation and a destination.
Script service
The application includes a script service that can be accessed via $services.graph and which exposes the functions below.
- void addRing(DocumentReference origin, DocumentReference relation, DocumentReference destination)
- List<XWikiRelation> getRelations(DocumentReference vertex)
- List<DocumentReference> getDirectPredecessors(DocumentReference vertex, DocumentReference relation)
- String getDomain(DocumentReference relation)
- String getImage(DocumentReference relation)
- List<XWikiRelation> getRelations()
- removeRing(DocumentReference origin, DocumentReference relation, DocumentReference destination)
- List<DocumentReference> search(String text)
- List<DocumentReference> search(String text, DocumentReference relation)
Implementation
The application hinges on the XWiki classes below.
| XWiki class | Properties |
|---|---|
| Ring |
|
| StringRing |
|
| DateRing |
|
| BooleanRing |
|
An additional index field is added automatically by Solr when indexing Ring objects, via a SolrMetadataExtractor component having a higher priority than the default one provided by xwiki-platform. For instance, "The Jungle Book has author Rudyard Kipling" is indexed as follows in Solr:
property.ring.Graph.HasAuthor_string:[Ring.Rudyard Kipling].
In addition, all converse rings are indexed, but only partially at this stage, using the generic relation is connected to, because inverse relations are not handled at this stage, so that we have, for page wiki.Rudyard Kipling the following index entry:
property.ring.Ring.IsConnectedTo_string:[Ring.The Jungle Book].
The implementation consists in particular of the following components:
- XWikiRing: allows to create terms, relations and rings
- SolrRingIndexer: manages the index of rings
- SolrRingTraverser: runs queries across terms, rings and relations
Next steps
- Ability to add ring scalar values via a form.
- Support relation transitivity.
- Associate types with XWiki sheets.
- Store the rings in a graph database.
- Create rings using wiki syntax or macros: {{ring relation="wiki.HasAuthor" destination="wiki.Rudyard Kipling"}}The author of this book is Rudyard Kipling.{{/ring}}
- Handle inverse relations. For example the inverse of relation "has author" is relation "has authored".
- Display pages in livetables with ability to filter them by their rings.
Application name and related concepts
The application uses concepts which are at the crossroads of linguistics (sentences connecting words), logic (predicates) and mathematics (graphs). The main structure on which it builds on consists of a triple (a,R,b) comprising three terms:
- a referent: "in logic, the word referent is sometimes used to denote one of the two objects participating in a relation, the other being called the relatum.".
- a binary relation: "a binary relation over two sets A and B is a set of ordered pairs (a, b) consisting of elements a of A and elements b of B".
- a relatum.
A tuple (a,R,b) – more commonly noted R(a,b) – has different namings depending on the theoretical or usage context:
- Atomic formula in logic: "an atomic formula or atom is simply a predicate applied to a tuple of terms; that is, an atomic formula is a formula of the form P (t1 ,…, tn) for P a predicate, and the tn terms.".
- Statement in the semantic web community: an RDF statement is a triple of resources subject / predicate / object, where the predicate is a binary relation.
- Hyperedge in graph theory: an hyperedge is an n-uple connecting several vertices together. The terms a, R, b mentioned above can be seen as vertices, and (a,R,b) as an hyperedge, with the specificy that "R" is a relation.
The structure currently used by the application actually involves a fourth term, named "properties", in order to describe the triple (a,R,b) itself: properties are a handy shortcut for adding metadata about a triple, just like what property graphs propose. Properties could actually rather be represented as individual atomic formula (rings) on their own, but this introduces some implementation complexity which might not be necessary at this stage.
So far, the word ring has been chosen to represent the core structure and for naming the application itself, mostly because it has a simple visual representation (however visually the circle should not be closed, since the ring can be navigated only in a given direction), it catches well the semantics of tying several terms together, and it it's easy to imagine a ring connecting several rings. Formally, a ring is just an atomic formula involving 3 terms (a relation and a pair of terms), with some properties. It's probably not a great idea to have chosen a new term but "atomic formula" might sound a bit scary to non logicians and is lacking a visual hint.
Hypergraph and hyperedges - Source: Wikipedia:Hypergraph
The higher-level structure consisting of a set of rings corresponds to an hypergraph, since each edge ties together several terms. It's currently a uniform 4-hypergraph since all edges have four vertices (referent, relation, relatum, properties), even though some are allowed to be empty (e.g. properties). The relatum term can either have an identifier or be a scalar (e.g. a given date or number). Each edge is also a vertex, so that edges can be involved in other edges.
Related projects
Resources
Design aspects
- Petits poucets, Keeping found things found — Nolwenn Maudet, http://petitspoucets.nolwennmaudet.com/
Relations
- Article The Subject-Object Relation
- Book A Modern Introduction to Logic
- Wikipedia:Referent
- Relations entry on Stanford Encyclopedia of Philosophpy
Graphs and hypergraphs
The data structure of the application is an hypergraph.
- Articles
- Graph databases go mainstream – Kurt Cagle, Forbes, July 2019
- Graphs in mathematics – Wikipedia
- Graph traversal / search – Wikipedia
- Hypergraph definition – Wikipedia – A hypergraph is a generalization of a graph in which an edge can join any number of vertices.
- Modelling data with hypergraphs – Szymon Klarman
- Tim Berners Lee mail about a Giant Global Graph (2007)
- Books
- Graphes et hypergraphes – Claude Berge
- Graph databases in action – Dave Bechberger, Josh Perryman
- Hypergraph theory, an introduction – Alain Bretto
- The Practitioner's Guide to Graph Data – Denise Gosnell, Matthias Broecheler
- Libraries and models
- Databases
- User interface libraries
- GRANDstack framework - "Build full stack graph applications with GraphQL, React, Apollo, Neo4j", Demo: https://movies.grandstack.io/ with example queries, more examples
- SigmaJS
- Neo4j Bloom
Prerequisites & Installation Instructions
- At the moment, the application should not be installed from the XWiki Extension Manager due to an issue with the Component Module ( XCOMMONS-1814), but as follows:
- Go to the Ring section of the Adminstration and select the pages or spaces where the rings should be available.
Dependencies
Dependencies for this extension (org.xwiki.contrib:xwiki-ring-pages 1.0):
- org.xwiki.contrib:xwiki-ring-lib 1.0
