Help:Semantic annotation

Annotation is the most important part of Semantic MediaWiki for all editors. Annotations are special markup elements which allow editors to make some parts of the wiki's content explicit. Annotations are the basis for enhanced browsing and searching of CreationWiki. They also propagate changes in data on one page 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 should read Help:Editing first.

Annotations in Semantic MediaWiki are an extension of the category system. Categories are a means to classify articles according to certain criteria. For example, by adding to an article, the editor tags the article as discussing creationism. 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 categorization 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
The main reference and CreationWiki guideline for the use of categories is the Category Help page. 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", add

anywhere in the article. Please follow CreationWiki's existing guidelines for categorization. Every category has its own article, which can be linked to by writing  Category:Example category . The category's article can be empty, but we strongly recommend that you add a description that explains which articles should go into the category.

The relevance of categories to Semantic MediaWiki is twofold. One, the browse page browses categories in addition to other properties (see below). Two, while the ad hoc use of categories doesn't "break" Semantic MediaWiki, it does lead to inconsistency when you try to interpret semantics. The RDF export page applies precise semantics to categories, as described in its help page, that will be wrong for some usage.

Properties
Properties are "categories for values in articles". The syntax for them is simple,
 *  property name::value  .

Note the :: operator. This is the semantic operator or property assignment operator. It is the only operator that Semantic MediaWiki requires.

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
Consider the article on Abraham. This article contains many links to other articles in CreationWiki, such as "Isaac," "God," and so forth. However, the link to "Isaac" (among other such links) has a special meaning: the author added it because Isaac is Abraham's most famous son. To make this knowledge available to computer programs, we tag the link

Isaac

in the article text, identifying it as a link that describes a "son property." With Semantic MediaWiki, we add the property name and semantic operator in front of the link inside the brackets, thus:

father of::Isaac.

In the article, this text still displays as a simple internal link to "Isaac." The additional text "father of" is the name of the property that classifies the link to Isaac. 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. (Currently this applies only to the main namespace, i.e. the namespace for articles. But properties are also usable in other namespaces, like Help.) Property articles are in the "Property" namespace. You therefore can use the Special:Allpages page to find existing properties.

A property's page is used to do more than explain the property. It is also required to assign a type to a property (see below). If a property page stays empty, the type is assumed to be the page type that is the SMW datatype for establishing internal links. But if you want your property to be of any other type, you must assign that type.

There are various ways of adding properties to pages:

Turning values in text into Properties
There is other useful information in articles besides links. For example, the water article contains multiple numbers giving density, melting and boiling and triple points, and so on. To make this knowledge available to computer programs, you must "tag" the text. For example, to "tag" the text

1 g/ml

in the article to identify it as a density you first create a property titled Property:Density and then put that property name and the semantic operator in front of the text and surrounding it with  brackets, thus: Density::1 g/ml.

Now this would work, but left as is, it would create an internal link to the phrase "1 g/ml", and that would not be desirable. Furthermore, you would miss the opportunity to sort water (and other pure substances) by their densities, without having to build a table for them from scratch. To do this, you must assign the property a type.

Types of Properties
We want to be able to tell Semantic MediaWiki at a minimum that "density" is a number, not a link to an article. To do this, you specify a type for the "density" property. Semantic MediaWiki has several built-in datatypes that we can choose for properties. For our density example, the appropriate type might be Type:Number; the prefix "Type:" is again a separate namespace. We want to give property "Density" a special property that assigns it to "type:number". To support type assignment, 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:Atomic number 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. They each have a special built-in meaning and are not evaluated as are other properties. (On CreationWiki, all special types have descriptive articles and are categorized. This is not necessary to their function, but is necessary to their documentation, organization, and ease of use.)

N-ary Properties
N-ary properties are properties that take more than one value at a time. N-ary properties are, therefore, collections of values, not merely choices. The chief utility of using an N-ary property instead of a collection of unary (one-value) properties is that sometimes one never anticipates sorting or querying the individual values, but only the collection. A contact address is one example of an n-ary property.

To declare an n-ary property, you use an n-ary has type::xxx declaration, and declare each anticipated member of the collection. For example, in order to declare a complete contact address property, use code like this:

has type::string;string;string;string;string;email

The above code would create an address property calling for the specification of a name, a street address, a city name, a state/provincial name, a postal code, and an e-mail address.

To use an n-ary property, you specify every member of the collection one after the other, in the order of their declared types, separated by semicolons. For example, to specify a contact address declared as above, annotate this in the relevant article:

Contact::John Doe;1234 Pine St.;New York;NY;10012;johndoe@isp.net

If you don't have all the values for all the members of the collection, specify "" or "?" for each value that you must omit.

Advantage: annotation and later recall of contact information is much simpler and easier.

Disadvantages:
 * 1) Queries will not sort on any member of the collection (except possibly the first).
 * 2) Queries cannot accept conditions on members of the collection. For example, a query for "all contacts in a given city" would not run.
 * 3) N-ary properties cannot accept any of the qualifying special properties like allows value:: or display units:: or provides service:: . Therefore the n-ary relationship does not support enumerations (though it does support Booleans; see below).

An editor can, however, control the display of the information, in exactly the same manner as one can control the display of any internal link. Tags such as

are still allowed.

''The administration has asked the SMW development team to consider enhancing n-ary properties to remove the above disadvantages. Watch all Semantic Help pages carefully for updates and added features.''

Datatypes
Datatypes are very important for evaluating properties. First, the datatype determines how tools should handle the given values, e.g. for displaying values and sorting values in search results. Second, 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 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, even a page-type 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.

Datatypes and units of measurement
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. (You can also obtain this from Category:Type.) Basic types include: 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).
 * Type:String (short text strings)
 * Type:Number (integer and decimal numbers with optional exponent)
 * Type:Page (links to pages, the default)

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 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
There are some special built-in datatypes which support more complicated formats and unit conversions.


 * Type:Enumeration is an alias for Type:String. Originally it was a string that restricted user input to a defined set of values. Beginning with SMW 1.0, Type:String can do the same thing--and Type:Enumeration behaves exactly like a string if you specify no allowable values.
 * Type:Boolean is a special type that stores values as either logical true or logical false. The major utility of this type lies in controlling prrecisely the display of the true or false values in queries, and also making these true-or-false values available in RDF feeds. Mere categorization of articles cannot achieve thess results.
 * Type:Text 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. Therefore, Semantic MediaWiki has done this for us.
 * 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, but only in the Unix Era. This type is still somewhat experimental. The developers speak hopefully of supporting non-Gregorian (historic) calendar models in the future.
 * Type:Historical date: This is an implementation of dates developed here on CreationWiki as a special development project of the administration. It uses a double-precision float to store Julian Days, and thus can quite easily represent any date in recorded human history. It, too, is still experimental, and attempts to annotate times with dates are still unpredictable. However, this data type now supports annotation of Julian or Gregorian dates, Hebrew dates, and ancient Biblical dates in nearly all the languages of CreationWiki.

For specifying URLs and emails, there are some special variations of the string type: 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.
 * Type:URL and Type:URI make external links to their URL objects. URI is an alias for URL. Warning: Ad hoc use of Type:URL will overcrowd your factboxes with lots of external links. Use this type sparingly. See our annotation guidelines for details.
 * 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.

Semantic templates
Editors can 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
In addition to the type-assignment property Property:Has type, SMW has other special properties that you must know about, for two reasons:
 * 1) The names of these properties are reserved words.
 * 2) They can be very useful to you in building custom abstract data types.

The full list of special properties follows:


 * Allows value. Turns a string-type property into an enumerated property by restricting the values it can take to a defined set of allowed values. To use it, specify Allows value::xxx for every xxx that you want your enumerated string to accept.
 * Corresponds to. Used in a Type declaration to build linear custom types. To use, declare one instance of this property for every conversion ratio that your custom type requires.
 * Display units. Used in a property of a custom linear type to restrict the displayed units to a small subset of all the units that are allowed.
 * Equivalent URI. Specifies a URI to content outside this wiki that is the same as, or similar to, related content inside it. Not recommended for use in CreationWiki.
 * Has type. Explained above; this is the property that assigns data types to the properties of those types.
 * Imported from. Specifies an external resource for any imported information feed.
 * Provides service. Sets up a service link.
 * Subproperty of. Declares one property to be the subproperty of another. Queries on the master property will capture articles that have annotations in the master property and all of its subproperties. However, that content will not display under the master-property heading. Other wiki administrators have already asked the SMW development team to allow subproperty content, if applicable, to display under the heading of the master property.

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" as formerly used in CreationWiki
In earlier versions of SMW, properties with Type:Page were known as relations and had their own namespace. Only these used double colons (::) as an assignment operator. All other properties (numbers, strings, etc.) were known as attributes and used the Pascal assignment operator (:=) for attribute assignment.

SMW 1.0 unifies relations and attributes, calling them properties, and uses a single namespace "Property:". The Relation namespace is deprecated and, in fact, no longer used. The default datatype for undeclared properties is Type:Page. Page-type properties correspond to the old "relations."

SMW still supports := but here on CreationWiki we insist that you use :: for all property annotations. The equals sign in the Pascal-style assignment operator := cannot be used properly within MediaWiki template parameters, whereas :: causes no problems in our environment.

The Type:Boolean type is temporarily disabled. However, the developers of Semantic MediaWiki have recently announced plans to reinstate this type in the next release candidate. (They have also pledged to support a new type of query called a "Boolean printout" that might obviate the Boolean type entirely. Watch this page, and the Help:semantic annotation guideline, for updates.)

CreationWiki never used attributes before. All relations have since been redefined as page-type properties. The administration desires that editors build and use non-page-type properties extensively in order to use SMW to its best advantage.

pt:Ajuda:Anotação semântica