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.
Examples
::(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.
