Help:Semantic annotation guideline
This is CreationWiki's official guideline and style guide for annotations. It governs the naming of properties and custom types, and when and how to use annotation.
Semantic annotation can be done in any language or even with numbers. However, one can often state the same thing in more than one way. CreationWiki has established these guidelines in order to enforce consistency in property building and use.
How to name Properties
Page-type properties are best named with nouns or passive participles followed by prepositions, or by nouns alone. Non-page-type properties should always have nouns or noun phrases for names. For example:
- For non-relational properties
[[First Name::John]] [[Age::31]] [[Date of birth::1975-12-30]]
- For relational or page-type properties
[[Located in::Asia]] [[President of::United States]] [[Member of::European Union]]
Always check to see what properties already exist. Use Special:Properties for a quick list of all properties used in the article namespace. Also see the list of reserved words in SMW. Double-check by using Special:Allpages and searching the Property namespace.
Sometimes you need to distinguish a present state from a past state. For example: "was president of" is not the same as "is president of". If you want to ask for all the presidents of the US over time you need to query both, the past and the current presidents. Using the property "president of" would avoid this problem, because you can easily use it for incumbent and former presidents.
Choosing better names
- The current President
In the section before we discussed how to specify the time a person was the President of the US. Using only "was president of" is not the best solution for all questions, because someone could ask for the presidents of the US in chronological order. Therefore you need the exact dates. For George Washington this could look like:
But even this will not suffice, because it says nothing about which kind of president the person was. In that example George Washington could have been the president of a chess-club. Therefore you must use such names as:
[[president of United States since::1789]]
[[president of United States till::1797]]
which describes George Washington very well. The new property simply derive from the first one, which says, that the new property are a special kind of the old ones. When the user is now searching ie. for "president since" she will also find articles including "president of United States since".
When and When Not to Annotate
These guidelines are subject to change without notice, upon administrative review as to their appropriateness and completeness. To propose additions, modifications, or rescissions from these guidelines, please address your concerns to the Coffeehouse.
- Do not annotate every external link in an article. This will produce an unreadable factbox. For that reason also, do not use the Type:URL in a template like Bible ref that might find as many as a hundred uses in a single article (like Biblical chronology dispute). Instead, choose your external-link annotations carefully. Remember that every URL that you annotate will appear in the factbox and will be browseable and searchable.
- Do not annotate e-mail addresses, except to provide points-of-contact in biographical articles, or articles describing organizations.
- Do not annotate text with the text data type without a clear rationale for doing so--say, if you want a particular block of text to show up directly in a structured search. Remember that annotated blocks of test will appear in the factbox and can clutter it up.
- Do not annotate dates earlier than the twentieth century with date type properties. Such annotation will fail. Use Type:Historical date instead. (The SMW development team has accepted our code for a proper historical date and pledges to enhance their own Date datatype with this code. However, the SMW developers will not guarantee continued support for Anno Mundi date annotations, as our datatype provides.)
- Do not annotate text with a page-type property unless you have a good and sufficient reason to write an article on that subject. Here on CreationWiki, we do not plan, for example, to have articles on all the States within the United States. By annotating States as strings, we can still make individuals and organizations searchable or tabulable by inline query without having to create a separate article for every States in which such an individual may reside, or such an organization might have its headquarters.
- Do annotate any commonly reported number or string in an article. Atomic numbers and masses, CAS registry numbers, and SMILES formulae are good examples.
- Do learn how to use templates to automate semantic annotation--but be sure to document your templates properly.
- Do consider carefully when n-ary properties might be more appropriate to declare than large numbers of properties for values that always occur together and are never queried separately.
- Do learn the various data types and special properties, what they do, and how they work together. See Help:Semantic annotation for full particulars, along with explanatory Property and Type pages.
- Declare all properties. By default, a new property has the type page. In order to assign a property to a different type, you must declare it.
- Categorize all properties and types. At a minimum, every property belongs in Category:Property, and every type in Category:Type. All properties and types also belong in Category:Semantic MediaWiki. Lastly, categorize any properties and/or types that you use regularly by assigning them to the categories that you regularly apply to articles--so that you can find them easily. Properties and types are valuable resources, as are images in the Media Pool. You should organize them accordingly.
- Do not use the Relation namespace. SMW will no longer recognize it. (The administration is considering the deletion of all remaining articles in that namespace.)
This page is part of the CreationWiki Semantic MediaWiki Help series - prepared to assist editors in becoming productive members of the CreationWiki community. Browse the Table of Contents