Extension:Semantic Internal Objects

Description
Semantic Internal Objects is an extension to MediaWiki, based on Semantic MediaWiki. It defines a parser function, '#set_internal', which is used to define "internal objects" within the Semantic MediaWiki system. There are complex types of information sometimes known as 'n-ary relations' that involve more than one data value associated together. A simple example is in a cooking recipe: a recipe may call for 1 cup of flour, and the values "1", "cup" and "flour" must be encoded together - by themselves, the values are not meaningful (the third value has meaning, though not all of the meaning it could have). Such information can be stored already in SMW using many-valued properties, though this approach has problems with flexibility and queriability. Instead, #set_internal can be used to define "internal objects" within a page, which can then be queried as normal SMW pages would; a row of a recipe would be a good example of data that could be defined using #set_internal.

This extension requires version 1.4.2 or greater of Semantic MediaWiki. (Note: if you're a Ubuntu 9.04 user, the default SMW version is 1.4.0 via aptitude/apt-get)

Semantic Internal Objects was funded by STAR Software (Shanghai) Co., Ltd., a member of the STAR Group.

Download
You can download the Semantic Internal Objects code in either one of these two compressed files:


 * semantic_internal_objects_0.5.tar.gz
 * semantic_internal_objects_0.5.zip

You can also download the code directly via SVN from the MediaWiki source code repository, at http://svn.wikimedia.org/svnroot/mediawiki/trunk/extensions/SemanticInternalObjects/. From a command line, you can call the following:

svn checkout http://svn.wikimedia.org/svnroot/mediawiki/trunk/extensions/SemanticInternalObjects/

Installation
To install this extension, create a 'SemanticInternalObjects' directory (either by extracting a compressed file or downloading via SVN), and place this directory within the main MediaWiki 'extensions' directory. Then, in the file 'LocalSettings.php', somewhere below the inclusion of Semantic MediaWiki (both the main 'include_once' line and the 'enableSemantics' line), add the following line:

For most versions of Semantic MediaWiki before 1.5, you will also need to add one line to the SMW code: in the file '/extensions/SemanticMediaWiki/includes/storage/SMW_SQLStore2.php' at the very bottom of the function deleteSemanticData, add this line:

In version 1.4.3 of SMW, this is around line 1925; in version 1.4.2, it's around line 1810.

That is how the section should look after insertion of the code: Of course, if this line is already there, you don't need to add it.

Enabling RDF export
If you're using version 1.5.1 of Semantic MediaWiki, internal objects will be automatically included when an RDF export is done. If you want RDF export of SIO to work with version 1.5 of SMW, you will have to add a few lines to SMW. In the 'SemanticMediaWiki' directory, in the file /specials/Export/SMW_SpecialOWLExport.php, right after the line: (around line 678), add the following code:

Unfortunately, RDF export will not work with versions of SMW before 1.5.

Author
Semantic Internal Objects was written by Yaron Koren, reachable at yaron57 -at- gmail.com. Important contributions were made by Jamey Wood.

Version
Semantic Internal Objects is currently at version 0.5.

The version history is:
 * 0.1 - August 19, 2009 - Initial version
 * 0.2 - January 1, 2010 - Database calls turned into a single transaction; support for many languages added
 * 0.3 - February 10, 2010 - Support added for SMW 1.5 and properties of type 'Text'
 * 0.4 - March 2, 2010 - Better handling for automated SMW updating; handling of lists of values added, via '#list'; support for values containing '='
 * 0.4.1 - May 13, 2010 - Support added for SMW 1.5.1; possible fix for some data-refresh issues
 * 0.5 - June 4, 2010 - RDF export added; handling added for new coordinates representation in Semantic Maps 0.6

Usage
The syntax of #set_internal is as follows:

It is very important to note that the first argument is a property pointing from the object, to the page, and not the other way around! This is a bit counter-intuitive, but it makes meaningful querying possible. To follow the recipe example above, the value of object_to_page_property could be 'Is part of recipe', but not 'has ingredient'.

A sample call to #set_internal would be:

This call would be placed in a page for a recipe, and it would define an object that had an automatically-generated name; if it were in a page called "Carrot cake", for instance, the object would be called "Carrot cake#1". If that page had subsequent calls to #set_internal, the objects that those calls generated would be called "Carrot cake#2", "Carrot cake#3", etc.

It should be noted that #set_internal does not display anything to the screen; display of the values has to be handled separately (this can be done easily if the function is called from a template).

One very important note relating to this is that a page, once displayed, must contain some actual text for the call to #set_internal to work. A page containing nothing but a call to #set_internal will not save any internal data, because the MediaWiki parser will be confused into thinking that the page is blank, and won't call the #set_internal function at all.

Querying internal objects
Internal objects, once stored, can be queried as if they were wiki pages. So the following query would show a table of all the recipes that contain more than 1/2 a cup of flour, and the number of cups they contain:

Note the "mainlabel=-" parameter in the query: that hides the names of the internal objects from users, since those names are confusing and basically meaningless.

Lists of values
You can have #set_internal store a list of values for a property, instead of just one. To do that, you just need to append "#list" to the property name. For instance, to record, in a page called "United States", the names of all presidents and their vice-presidents, you could have calls like:

The duplicate-information bug
A certain percentage of users of Semantic Internal Objects have encountered a problem where some internal objects are stored, and displayed, twice. This problem tends to occur after a template used by pages that store internal objects is resaved, or after a full SMW data refresh is called. Unfortunately, this bug has been very difficult for me (Yaron) to diagnose and fix because I've never been able to reproduce it myself. If you are having this problem and are willing to have me log in to your server to try to debug it, that would be very helpful - please contact me at yaron57@gmail.com

Bugs and feature requests
You should use the Semantic MediaWiki mailing list, semediawiki-user, for any questions, suggestions or bug reports about Semantic Internal Objects. If possible, please add "[SIO]" at the beginning of the subject line, to clarify the subject matter.

You can also send specific code patches to Yaron Koren, at yaron57 -at- gmail.com.