Help/Semantic links

Special markup elements allow editors to provide information on how to interpret links in the Rich Annotator System. Such pieces of information are called semantic annotations and they are created with a special markup.

Some annotations are necessary in the Rich Annotator System for automatic listings and for realize the main utility of the platform. Other annotations can be provided by editors as they like, but they should concert about it with administrators.

Classification and semantic annotations

Semantic annotations can be viewed as an extension of the category system. Categories are a means to classify pages. For example, by adding [[Category:Auteur(e)s]] to a page, it is tagged as describing in French a literary author.

Properties

Different pages have links and text values in them, but only a human reader knows what the link or text represents. Properties allow you to annotate any link or text on the page to describe the meaning of the hyperlink or text. This turns links and text into explicit properties of a page.

This enables users to go beyond mere categorisation of pages. Usage and possible problems with using these features are similar to the existing category system. Since categories and properties merely emphasize a particular part of a page's content, they are often called (semantic) annotations. Information that was provided in a page anyway, e.g. that À la recherche du temps perdu is a work of Marcel Proust, is now provided in a formal way accessible to software tools.

Besides annotations, administrators embed semantic queries into pages.

Creating properties

Properties are used by a simple markup, similar to the syntax of links: [[Property name::property value]]. This statement defines a value for the property of the given property name. The page where this is used will just show the text for value and not the property assignment.

The naming of properties is more important than one would probably expect at first. Property names should avoid ambiguity and confusion. Thus, it is good practice to create property names as a verb phrase. Here's an example that uses Maurice Carême and Médua to makes this practice more comprehensible:

One of Maurice Carême's works is Médua ↔ Médua is one of Maurice Carême's works.

In both cases one could assign a property named "Work", but this does not convey exactly the intended meaning. The first sentence says that Maurice Carême has a work entitled Médua, in other words he is the author of Médua. Therefore the better name for the property is "Author of":

One of Maurice Carême's works is [[Author of::Médua]].

Note that "Author of" is a property of "Maurice Carême" with value "Médua".

The second sentence states that Médua is one of Maurice Carême's works. Hence the better name for the property is "Work of" in this case. So the annotation avoiding ambiguity is as follows:

Médua is one of [[Work of::Maurice Carême]]'s works.

Note that "Work of" is a property of "Médua" with value "Maurice Carême".

Avoid using certain kinds of punctuation

Certain kinds of punctuation are to be avoided or have been declared invalid in property names, because they are also used as special syntax in semantic queries or they may cause problems for other reasons.

Do not use:

• :: (two subsequent colons) − a single colon should not cause any trouble
• - (hyphen) in initial position − for reasons to do with inverse properties
• . (dot) − operator used to link properties in concatenation
• | (pipe)
• # (number sign)

Best practice

• Use a verb phrase to describe a property.
• Use short names.

In-text annotation

Consider the page Médua. It contains links to other pages, such as "La Renaissance du livre" or "Maurice Carême". However, the link to "Maurice Carême" has a special meaning: it was put there since Médua is a work of Maurice Carême. To make this knowledge available to computer programs, one should "tag" the link [[Maurice Carême]] in the page text, identifying it as a link that describes a "work property". This is done by putting a property name and :: in front of the link inside the brackets, thus: [[Work of::Maurice Carême]].

In the page, this text is still displayed as a simple hyperlink to "Maurice Carême". The additional text Work of is the name of the property that classifies the link to Maurice Carême. As in the case of categories, the name of the property is arbitrary, but users should re-use properties that already appear elsewhere. See below property names to be used in the Rich Annotator System.

To simplify this re-use, every property has its own article, just as every category has an article.

In-text annotations are case-sensitive and if changed arbitrarily may cause content to be rendered invalid or unavailable during query execution.

Turning links into properties

There are various ways of adding properties to pages:

What it does	What you type	What is to note
Classify a link with the property "example property."	Classify a [[Example property::link]] with the property "example property."
Make alternate text appear in place of the link.	Make [[Example property::link|alternate text]] appear in place of the link.
To hide the property from appearing at all, use a space as the alternate text.	To hide the property [[Example property::link| ]] from appearing at all use a space as the alternate text.	The space after “|” is necessary. If left away, the pipe trick applies, but rarely with desirable effects. → Consider using annotations with #set instead.

Properties to be used in the Rich Annotator System

Back to contents