Help:Annotation

From NYC Resistor Wiki
Jump to: navigation, search

Semantic MediaWiki Docu

Annotations

Semantic templates

Custom units

Browsing and searching

Service links

Semantic search

Inline queries

External tools

Semantic Web

RDF export

Importing vocabulary

Ontology import

SPARQL endpoint

Installation

This page explains the basic annotation feature of Semantic MediaWiki. Annotations are special markup elements which allow editors to make some parts of the wiki's content explicit so that software tools can use them to assist users. In particular, semantic annotations provide the basis for more powerful search functions within the wiki. They also allow changes in data on one page to automatically propagate to other pages containing the same data (somewhat comparable with what can be done with templates). Users who are not familiar with the basics of editing MediaWiki should read Help:Editing first.

Annotations in Semantic MediaWiki can be viewed as an extension of the existing system of categories in MediaWiki. Categories are a means to classify articles according to certain criteria. For example, by adding [[Category:Cities]] to an article, the page is tagged as describing a city. Software tools can use this information to generate an ordered list of all cities in a wiki, and thus help users to browse the information.

Semantic MediaWiki provides a further means of structuring the wiki. Wiki pages have links and text values in them, but only a human reader knows what the link or text represents. For example, "is the capital of Germany with a population of 3,396,990" means something very different from "plays football for Germany and earns 3,396,990 dollars a year". SMW allows 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 an article. The property "capital of" is different from "on national football team of", just as the property "population" is different from "annual income".

This addition enables users to go beyond mere categorisation of articles. 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 an article's content, they are often called (semantic) annotations. Information that was provided in an article anyway, e.g. that Berlin is the capital of Germany, is now provided in a formal way accessible to software tools.


Categories[edit]

The main reference for the use of categories is the MediaWiki documentation on categories. Categories are used as universal "tags" for articles, describing that the article belongs to a certain group of articles. To add an article to a category "Example category", just write

[[Category:Example category]]

anywhere in the article. The name of the category (here: "Example category") is arbitrary but, of course, you should try to use categories that already exist instead of creating new ones. Every category has its own article, which can be linked to by writing [[:Category:Example category]]. The category's article can be empty, but it is strongly recommended to add a description that explains which articles should go into the category.

MediaWiki's categories have many different interpretations. For example, the category "City" might comprise all articles about particular cities, i.e. a member of this category is a city. Or it might describe the topic area of articles, such as articles on city squares, urbanism, etc. Or both. MediaWiki encourages this practical usage of categories: a category forms a collection of articles that are considered useful or interesting for users, and categories are organized so users can browse narrower or broader groupings and find related concepts.

Ad hoc use of categories doesn't "break" Semantic MediaWiki, but leads to inconsistency when you try to interpret semantics. SMW's Special:ExportRDF applies precise semantics to categories, as described in its help page, that will be wrong for some usage.

The advanced search functions of Semantic MediaWiki makes some categories superfluous, so that an SMW-enabled wiki might achieve a high degree of organization with fewer categories. For example, the subcategory "Large cities" could be replaced by a query for articles with Category:city with an area larger than 10 km², or a population larger than 1,000,000.

Properties[edit]

Properties can be viewed as "categories for values in articles". The syntax for them is simple,

[[property name::value]].

value appears in the text, but behind the scenes it has been classified as property name.

This works whether the value is a link or regular text. However, for clarity we'll consider turning links into properties, as regular text requires an additional step.

Turning Links into Properties[edit]

Consider the Wikipedia article on Berlin. This article contains many links to other articles, such as "Germany," "European Union," and "United States." However, the link to "Germany" has a special meaning: it was put there since Berlin is the capital of Germany. To make this knowledge available to computer programs, one would like to "tag" the link

[[Germany]]

in the article text, identifying it as a link that describes a "capital property." With Semantic MediaWiki, this is done by putting the property name and :: in front of the link inside the brackets, thus:

[[capital of::Germany]].

In the article, this text still is displayed as a simple hyperlink to "Germany." The additional text "capital of" is the name of the property that classifies the link to Germany. As in the case of categories, the name of the property is arbitrary, but you should try to use re-use properties that already appear elsewhere.

To simplify this re-use, every property has its own article in the wiki, just as every category has an article. You can see all the properties in use in the wiki with the Special:Properties page. Just as category articles are prefixed with "Category:", all property articles are prefixed with "Property:" to distinguish them from other articles. So you can also use the Special:Search page to find existing properties. As with categories, a property's article can be empty, but you are strongly recommended to add a description that explains the intent of the property and its proper usage.

There are various ways of adding properties to pages:

What it does What you type
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 relation::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 relation::link| ]] from appearing at all
To make an ordinary link with :: without creating a property, escape the markup with a colon in front, e.g.
The C++ :: operator.
The [[:C++ :: operator]].
To assign one value to multiple properties, add :: between each name,
e.g. link.
e.g. [[property1::property2::link]]. 

Turning values in text into Properties[edit]

There is other useful information in articles besides links. For example, there is a number in the Berlin article giving its population. To make this knowledge available to computer programs, one would like to "tag" the text

3,396,990 

in the article, identifying it as a value for the "population property". With Semantic MediaWiki, this is done by putting the property name and :: in front of the text and surrounding it with [[ ]] brackets, thus:

[[population::3,396,990]].

This works fine. However, it creates a link to a 3,396,990 page, and having an article for every population value probably does not make sense. Furthermore, if you wanted to create a list of all German cities ordered by population, numeric order is different from the alphabetical order that you would expect for article names. For example, in alphabetical order, "1,000,000" comes before "345".

Types of Properties[edit]

We want to be able to tell Semantic MediaWiki that "population" is a number, not a link to a page in the wiki. The way to do this is to specify a type for the "population" property. Semantic MediaWiki has several built-in datatypes that we can choose for properties. For our population example, the appropriate type is called Type:Number; the prefix "Type:" is again a separate namespace that distinguishes descriptive articles about types from normal pages. We want to give property "population" a special property that specifies it has "type:number". To support this Semantic MediaWiki has a built-in special property called Property:Has type. We use the same syntax for this special property as for any other property, so in the Property:Population article, we write:

[[has type::number]]

(You don't need to specify the Type: namespace here.)

Semantic MediaWiki knows a number of special properties like Property:has type. Regardless of whether these properties have their own articles in the wiki, they have a special built-in meaning and are not evaluated like other relations.

Datatypes[edit]

Datatypes are very important for evaluating properties. Firstly, the datatype determines how tools should handle the given values, e.g. for displaying values and sorting values in search results. Secondly, the datatype is required to understand which values have the same meaning, e.g. the values "1532", "1,532", and "1.532e3" all encode the same number. Finally, some datatypes offer special functions, as will be described below. For these reasons, every attribute has a datatype.

The reason we didn't have to specify a datatype for the "capital of" property above is that the default datatype is Type:Page, which displays as a link. (Note that if you change the datatype of a property later on it does not affect the annotations of existing articles until they are saved again or purged.) Even though Type:Page is the default, you should explicitly specify a datatype to every property, just to prevent confusion or later redefinition with an unintended type.

The same mark-up for properties that are links to pages also works for properties of other datatypes. Here are some more examples.

What it does What you type
Assign the value 1,234,567 to the property "example."
Assign the value [[example::1,234,567]] to the attribute "example."
Assign a value of about a million, but showing different text in the article.
Assign a value of [[example::999,331|about a million]], 
but showing different text in the article.
Specifying the type in a property's article:
This property is an integer number.
Giving the type in an property's article:
This attribute is an [[has type::Type:Number|integer number]].
Combining MediaWiki markup with property values:
John's username is

john
Hint: Use a template for this.

Combining MediaWiki markup with property values:
John's username is 
[[username::john|[mailto:john@mailinator.com john]]].

Datatypes and units of measurement[edit]

Using different types, properties can be used to describe very different kinds of values. A complete list of available types is available from Special:Types. Basic types include:

  • Type:String (text strings)
  • Type:Number (integer and decimal numbers with optional exponent) (planned for SMW 1.0, this will replace Type:Integer and Type:Float in earlier versions)
  • Type:Page (links to pages, the default)

These can be used creatively for very different purposes. For instance, attributes of type string can be used for encoding phone numbers (which in fact can contain non-numeric symbols).

Units[edit]

Type:Number allows a unit after the numeric value to distinguish values (e.g. "30.3 mpg" versus "47 km/liter"), but does not know how to convert between them. (In SMW 0.6, providing units leads to the warning "this attribute supports no unit conversion" in the factbox and query results, Template:SMWbug filed.)

To support automatic conversion and multiple unit formats, you can define your own datatype with custom units. These automatically convert values to and from standard representations, so that users are free to use their preferred unit in each article yet still query and compare with attribute values in other articles.

Special datatypes[edit]

There are some special built-in datatypes which support more complicated formats and unit conversions.

  • Type:Enumeration is like Type:String but restricts the value of an attribute to a limited set of values.
  • Type:Boolean restricts the value of an attribute to true/false (also 1/0 and yes/no).
  • Type:Text (new in SMW 1.0) is like Type:String but can have unlimited length;
  • Type:Temperature can't be user-defined since converting temperature units is more complicated than multiplying by a conversion factor.
  • Type:Geographic coordinate describes geographic locations. It includes functions for recognizing different forms of geographic coordinates, and it dynamically provides links to online map services.
  • Type:Date specifies particular points in time. This type is still somewhat experimental, but may feature complex conversions between (historic) calendar models in the future.

For specifying URLs and emails, there are some special variations of the string type:

  • Type:URL and Type:URI make external links to their URL objects.
  • Type:Annotation URI: attributes of this type are interpreted as relations to external objects, denoted by the URI. They are special since they are interpreted as annotation properties on export. See the type page for documentation.
  • Type:Email stores emails as a string datavalue, but automatically links them (with mailto:) within the page.

Values of these URL types appear as links in the text of the page. However, note that in an inline query, they display wiki markup instead of a link.

Semantic templates[edit]

It is possible to embed semantic annotations into MediaWiki templates. This can help to simplify syntax for the users, to support the consistent usage of annotations, and to quickly obtain a great amount of semantic data by annotating existing templates. Read Help:Semantic templates for details.

Special properties[edit]

We mentioned the special property Property:Has type that you use to tell SMW the datatype of a property. SMW has other predefined special properties that have special meaning (even if you do not create property pages for them in your wiki). You cannot use these names for your own properties. In SMW 1.0, the list of special properties is

Allows value, Corresponds to, Display units, Equivalent URI, Has type, Imported from, Provides service, and Subproperty of.

Additionally, Display unit is an alias for Display units.

These internal special properties do not appear in the Special:Properties list, you cannot query for them, and a special property's page does not show the pages using the property.

"Relations" and "Attributes" in earlier versions[edit]

In earlier versions of SMW, properties with Type:Page were known as relations and only those used double colons (::) as the separator between property name and link text. All other properties (numbers, strings, etc.) were known as attributes and had to use colon equals (:=) as the separator.

SMW 1.0 unifies relations and attributes, calling them properties, and uses a single namespace "Property:". The default datatype for undeclared properties is Type:Page, but it is strongly recommended that you declare every property's type to clarify its intended use for other editors. SMW still supports := but it is recommended that you use :: for all property annotations. The reason is that the equality symbol contained in := cannot be used properly within MediaWiki template parameters, whereas :: causes no problems in most environments.

See Upgrading from SMW 0.7 to SMW 1.0 for other changes in SMW 1.0; if you're still using the older version of SMW, see see Help:Annotation (SMW0.7) for documentation of Annotations in version 0.7.

Template:Smw