Help:Property naming

From semantic-mediawiki.org
Property naming
Naming guidelines and convention for properties
Keywords
Table of Contents

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 Berlin and Germany to makes this practice more comprehensible:

Germany's capital is Berlin. ↔ Berlin is the capital of Germany.

In both cases one could assign a property named "Capital", but this does not convey exactly the intended meaning. The first sentences says that Germany has a capital called Berlin. Therefore the better name for the property is "Has capital":

Germany's capital is [[Has capital::Berlin]].

The second sentence states that Berlin is the capital of Germany. Hence the better name for the property is "Is capital of" in this case. So the annotation avoiding ambiguity is as follows:

Berlin is the capital of [[Is capital of::Germany]].

Note that in the first case "Has capital" is a property of "Germany" with value "Berlin" whereas in the second case "Is capital of" is a property of "Berlin" with value "Germany".

Avoid reserved names[edit]

For technical reasons reserved names cannot or should not be used.1 Reserved names identify a special kind of syntax or represent magic words, special pages, behaviour switches, namespaces etc. These are defined for MediaWiki2, Semantic MediaWiki3 and any other software that may be use as an extension for both. Thus it is advisable or even required to avoid too generic names like e.g. "category"; use "Belongs to category" instead. Semantic MediaWiki 3.0.0Released on 11 October 2018 and compatible with MW 1.27.0 - 1.31.x. brought configuration parameter $smwgPropertyReservedNameListSets which names are reserved from usage as property names which provides an extendable list of reserved names which will cause warnings to be shown to the user if a reserved name is being used.4

Avoid using the name of a datatype[edit]

For technical reasons a property name should not be the same as the name of one of the datatypes. So an annotation like e.g. [[Code::Qsdr-5t7Z-b99N]] will not serve the intended purpose, since the assigned datatype will always be "Code" and cannot be changed to "Text". However, to name the property "Is registration code" or something alike is the better alternative for this in the first place anyway.

Avoid using certain kinds of punctuation[edit]

Certain kinds of punctuation are to be avoided or have been declared invalid5 in property names, because they are also used as special syntax in semantic queries or they may cause problems for other reasons.

As a general rule you are advised to only use characters available in the American Standard Code for Information Interchange (ASCII).6
Examples
  • :: (two subsequent colons) − a single colon should not cause any trouble
  • : (single colon) − a single colon should be avoided, see 7
  • - (hyphen) in initial position − for reasons to do with inverse properties
  • . (dot) − operator used to link properties in concatenation8
  • | (pipe)
  • # (number sign) − for datatype "Page"Holds names of wiki pages, and displays them as a link since it is interpreted as part of a subobject declaration.9 10
Semantic MediaWiki 2.5.0Released on 14 March 2017 and compatible with MW 1.23.0 - 1.29.x. introduced configuration parameter $smwgPropertyInvalidCharacterListSets a list of invalid characters which are not allowed to be used for property naming5 helping wiki system administrators to exclude certain characters from being used right away.

Best practice[edit]

  • Use a verb phrase (recommended) to describe a property
  • Use short names. Some Result formats like CSV or JSON put property names in URLs with API calls. In case you have a lot of/long property names the resulting URLs can become too long resulting in a call to the page Special page "Ask" instead of delivering a CSV or JSON file.
  • "Style Guidelines for Naming and Labeling Ontologies in the Multilingual Web" 11 contains some general guidelines how to name properties and URI's

See also[edit]





References

  1. ^  Semantic MediaWiki: GitHub issue gh:smw:2835
  2. ^  https://phabricator.wikimedia.org/source/mediawiki/browse/master/languages/messages/MessagesEn.php
  3. ^  https://github.com/SemanticMediaWiki/SemanticMediaWiki/blob/master/i18n/extra/en.json
  4. ^  Semantic MediaWiki: GitHub pull request gh:smw:2840
  5. a b  Semantic MediaWiki: GitHub pull request gh:smw:2282
  6. ^  Semantic MediaWiki: GitHub issue comment gh:smw:3134:423825894
  7. ^  Semantic MediaWiki: GitHub issue gh:smw:5232
  8. ^  Semantic MediaWiki: GitHub issue gh:smw:676
  9. ^  Semantic MediaWiki: GitHub issue comment gh:smw:1087:123476927
  10. ^  Semantic MediaWiki: GitHub pull request gh:smw:1568
  11. ^  Elena Montiel-Ponsoda, Daniel Vila Suero, Vila Suero Villazón-Terrazas Boris D Montiel-Ponsoda E., Gordon Dunsire, Elena Escolano Rodríguez, Asunción Gómez-Pérez. "Style guidelines for naming and labeling ontologies in the multilingual web". Informatica (2011).