Help:Properties and types

{{SMW user TOC}}
'''Properties and types''' are the basic way of entering semantic data in [http://semantic-mediawiki.org/wiki/Semantic_MediaWiki Semantic MediaWiki]. Properties can be viewed as «categories for values in wiki pages». They are used by a simple mark-up, similar to the syntax of links in [[MediaWiki]]:

: <tt><nowiki>[[</nowiki>''property name''::''value''<nowiki>]]</nowiki></tt>

This statement defines a <tt>''value''</tt> for the property of the given <tt>''property name''</tt>. The page where this is used will just show the text for <tt>''value''</tt> and not the property assignment.

Existing links can be directly augmented with such property information, while other '''types of data''' (such as numbers or calendar dates) need an additional editing step. 

== Turning links into properties ==

Consider the [[wp:Berlin|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

 <nowiki>[[Germany]]</nowiki>

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

 <nowiki>[[capital of::Germany]]</nowiki>

In the article, this text still is displayed as a simple hyperlink to «Germany». The additional text <tt>capital of</tt> 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 users should try to 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 <tt>Category:</tt>, all property articles are prefixed with <tt>Property:</tt> to distinguish them from other articles. So you can also also use MediaWiki's [[Special:Search]] page to find existing properties. As with categories, a property's article can be empty, but it is 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:

{| border="1" cellpadding="2" cellspacing="0"
 ! What it does 
 ! What you type
 |-
 | Classify a [[link]] with the property "example property."
 | <pre><nowiki> Classify a [[example property::link]] with the property "example property."</nowiki></pre>
 |-
 | Make [[link|alternate text]] appear in place of the link.
 | <pre><nowiki>Make [[example property::link|alternate text]] appear in place of the link.</nowiki></pre>
 |-
 | To hide the property [[link| ]] from appearing at all, use a space as the alternate text.
 | <pre><nowiki>To hide the property [[example property::link| ]] from appearing at all</nowiki>
use a space as the alternate text.</pre>

'''Note:''' The space after <nowiki>|</nowiki> is necessary. If left away, the MediaWiki [[wp:Help:Pipe trick|pipe trick]] applies, but rarely with desirable effects. Even if a space is given, SMW will not print anything, which should be the desired result in most cases (to make a space appear in the text, use <tt>&amp;nbsp;</tt> as a space symbol).
 |-
 | To make an ordinary link with :: without creating a property, escape the markup with a colon in front, e.g.<br />The [[:C++ :: operator]]. 
 | <pre><nowiki>The [[:C++ :: operator]].</nowiki></pre>
 |-
 | To assign one value to multiple properties, add :: between each name, <br />e.g. [[link]]. 
 | <pre><nowiki>e.g. [[property1::property2::link]]. </nowiki></pre>
|}

== Turning values in text into properties ==

There is other useful information in wiki articles besides links to other articles.  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 <nowiki>[[ ]]</nowiki> brackets, thus:
 <nowiki>[[population::3,396,990]].</nowiki>

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". 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; see the next section for more information.

== Data types for properties ==

Semantic MediaWiki has several built-in ''data types'' that we can choose for properties.  For our previous 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:

 <nowiki>[[has type::number]]</nowiki>

(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 properties.

Data types are very important for evaluating properties. Firstly, the data type determines how tools should handle the given values, e.g. for displaying values and sorting values in search results. Secondly, the data type 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 data types have special behavior, as will be described below. For these reasons, every property used should be defined with a data type.

The reason we didn't have to specify a data type for the "capital of" property above is that the default data type is [[Type:Page]], which displays as a link. Even though Type:Page is the default, you should explicitly specify a datatype for 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.

{| border="1" cellpadding="2" cellspacing="0"
 ! What it does 
 ! What you type
 |-
 | Assign the value 1,234,567 to the property "example".
 | <pre><nowiki>This page has a value for "example" of [[example::1,234,567]]."</nowiki></pre>
 |-
 | Assign a numeric value, but showing different text in the article.
 | <pre><nowiki>This page has a value for "example" of [[example::999,331|about a million]].</nowiki></pre>
 |-
 | Specifying the type in a property's article, e.g.<br/>This property is a [[Type:Number|number]].
 | <pre><nowiki>This property is a [[has type::number]].</nowiki></pre>
 |- 
 | Combining MediaWiki markup with property values, e.g.<br/>John's username is [mailto:john@example.com john]<br/>''This is not recommended; you should use a [[Help:Semantic templates|template]] instead.''
 | <pre><nowiki>John's username is [[username::john|[mailto:john@example.com john]]].</nowiki></pre>
|}

=== List of data types ===

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]]. The available types are:

{{List of data types}}

=== Enumerations and "Allows value" ===

SMW does not have an "enumerated" data type, i.e. a type that has a limited set of allowed values; instead, for any property, you can limit its possible values by using the special property [[Property:Allows value]] to enumerate its permitted values. This works for every data type.

=== Units ===

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. To support automatic conversion and multiple unit formats, you can define your own datatype with [[Help:Custom units|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 property values in other articles.

== Special properties ==

We mentioned the special property [[Property:Has type]] that you use to define the data type 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, but since [[SMW 1.4.0]] you can use them in browsing and querying interfaces just like all other properties. For more information, see [[:Category:Special property]] and the individual property pages.

== Silent annotations using #set ==
Instead of using the standard double-brackets markup, you can also define semantic data using the #set parser function. This function takes in pairs of property names and values and stores them semantically; but it does not print anything to the screen. An example call would be:

<pre>{{#set:population=3,396,990|country=Germany}}</pre>

The #set call is specifically helpful when trying to save a String or Text value that contains square brackets, such as wiki-links; such brackets often don't work with conventional SMW markup.

== Defining recurring events ==

Another type of complex data is recurring events, which are events that have multiple dates, defined according to a preset rule (such as a weekly meeting). You can define the date values for these using the #set_recurring_event parser function, which, like #set, is "silent" and does not print anything. An example call would be:

<pre>{{#set_recurring_event:property=Has date|start=January 4, 2010|end=June 8, 2011|unit=week|period=1|include=March 16, 2010;March 23, 2010|exclude=March 15, 2010;March 22, 2010}}</pre>

You can see [[Help:Recurring events]] for more information.

== Handling in earlier versions ==

In earlier versions of SMW, properties with [[Type:Page]] were known as ''relations'' and only those used double colons (<tt>::</tt>) 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 (<tt>:=</tt>) as the separator.

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 [[ow:Help:Annotation (SMW0.7)]] for documentation of Annotations in version 0.7.

{{docu|master page=Help:Properties and types|language=en|minversion=1.5.0}}