Extension:OttrParser

MediaWiki extensions manual

OttrParser Release status: beta
Implementation	Tag , Parser function
Description	Parsing OTTR statements and a suitable generation of wikicode that implements an equivalent behavior for such statement in the mediawiki.
Author(s)	Florian Schroeder, Oliver Tautz, Moritz Blum
MediaWiki	>= 1.34.0
License	GNU General Public License 2.0 or later
Download	Zip file GitHub: project page git repository URL [help ] commit history Note: No localisation updates are provided by translatewiki.net . README.md
Help	Help:Extension:OttrParser
Tags <ottr>, #ottrFunction
Hooks used ParserFirstCallInit

Tutorialː OttrParser Extension Docker Installation and Usage

The OttrParser extension parses OTTR Statements and produces wikitext that has equivalent behaviour, storing triples with the Semantic MediaWiki extension. It also provides automated form generation for the Page Forms extension.

For more information about general usage, see Help:Extension:OttrParser

The extension comes with an API to export and import ottr templates from .strottr files. Find more information on features and usage here: Help:Extension:OttrParser/API

WARNING! Because of the passing of the input to a python call, this extension is in the current form not considered as secure. Only trusted users should be allowed to edit pages when the extension is activated.

Docker Installation

We supply a docker image with a full installation of semantic MediaWiki and the OttrParserExtension, ready to go. It needs a linked mysql or mariadb database

If you have already set up your database and want to use it find info about how to use it here.

Otherwise you can use our docker-compose image to set it up automatically in another docker

1. Pull our current github repository with

   git clone --branch docker_release https://github.com/Oliver-Tautz/OttrParserExtension.git && cd OttrParserExtension
   

2. Pull and start the docker containers with

   sudo docker compose up -d
   

3. 

   OttrSmw Docker Database Settings

   Go to http:localhost:8080 and setup you wiki. Use the values from OttrSmw Docker Database Settings on the right. The Database password is root.
4. Save the LocalSettings.php somewhere you remember.
5. finish the installation with

   ./after_setup_script.sh -s LOCALSETTINGS_PATH
   

6.  Done You can now enter your wiki at http:localhost:8080
7. (Optional) Check out the API docs at http://localhost:5000
8. (Optional) Add #Custom Namespaces to the wiki

Docker Update

To update the extension, run

docker exec -w /var/www/html/extensions/OttrParserExtension OTTRWIKI git pull && ./setup_ottr_for_mediawiki.sh -a -p python3

Manual Installation

1. 1. clone the repo directly from your extensions folder with git clone https://github.com/Oliver-Tautz/OttrParserExtension.git
   2. or download and place the file(s) in a directory called OttrParserExtension in your extensions/ folder
2. 1. run setup_ottr_for_mediawiki.sh from the repository root. This will add a new python environment that will be used by the extension.
   2. or you can install the ottrToSmwPython package from source in any python environment you like with python -m pip install OttrParserExtension and change the OttrParserExtension/includes/Hooks.php such that it is called from your path. If the package is installed correctly you can find the path e.g. with the command which ottrToSMW
3. Add the following code at the bottom of your LocalSettings.php:

   wfLoadExtension( 'OttrParserExtension' );

4. install and add #Dependencies to you LocalSettings.php
5. The extension transfers some of the code into templates, for this you must import these pages, from the OTTR-Relevant-Pages.xml file in the repository of the extension, for Example via the Browser Interface on the Special:Import page.
6.  Done - Navigate to Special:Version on your wiki to verify that the extension is successfully installed.
7. (Optional) Start the OttrAPI with

   WIKIROOT/extensions/OttrParserExtension/ottr_env/bin/python3 WIKIROOT/extensions/OttrParserExtension/includes/ottrToSmwPython/ottrServer.py 

   and check out the documentation at http://localhost:5000
8. (Optional) Add #Custom Namespaces to the wiki Help:Extension:OttrParser

Manual Update

If you installed the extension via git, use

cd $MEDIAWIKI_ROOT/extensions/OttrParserExtension && git pull && ./setup_ottr_for_mediawiki.sh

where $MEDIAWIKI_ROOT is replaced by the path to the root folder of your mediawiki installation. You can also manually update the extension by downloading the files and overwriting the old ones. Then you still need to run

./setup_ottr_for_mediawiki.sh

from the extension folder.

Dependencies

MediaWiki Extensions:

• Semantic MediaWiki (Homepage)
• ParserFunctions
• Loops
• Arrays
• Page Forms
• InputBox
• AutoCreatePage

php plugins:

• php-curl

Custom Namespaces

By default, you can only define ottr templates in the template namespace. If you want to define ottr template in a custom namespace you need to

1. Define a new namespace in your LocalSettings.phpː

   define("NS_CUSTOM", 3000);
   $wgExtraNamespaces[3000] = "CUSTOM";
   $smwgNamespacesWithSemanticLinks[3000] = true;
   
   $egAutoCreatePageNamespaces = [
       NS_MAIN,
       NS_USER,
       NS_TEMPLATE,
       NS_CUSTOM
   ];
   

2. Add the namespace to your Settings.py. Add the value of $wgExtraNamespaces to the ottr_template_namespaces variable.

In a Nutshell

With OTTR you can define and instantiate templates with a defined syntax with additional features for parameters/arguments and also Lists of terms and different literal types handled by the parser. Using OTTR templates brings benefits, geared towards the field of RDF generation, among others:

• better abstraction
• uniform modeling
• moduloar, encapsulated patterns
• seperation of design and content

Main part is the template definition and the instantiation. The media wiki environment offers the separation part of template definition and instantiation through its inner logic on different pages: Definitions on pages in the Template namespace and the instantiation in other namespaces. A very simple example is shown in this section. The next section shows a more complex example that shows more of the features of the OTTR-language inside the pizza ontology.

Write a template (on a page in the Template Namespace and use the page name as the template name). For example a template for Pizzas, that is a subclass of the more general 'Pizza' class and has a name:

<ottr>
dpm:ExampleNamedPizza[ottr:IRI ?name, xsd:string ?label] :: {
    ax:SubClassOf(?name,ex:Pizza),
    ottr:Triple(?name, rdfs:label, ?label)
}.
</ottr>

Parameters can have different options (see the example in the next section), the variable names can be used inside the template hull. They have to start with a question mark. There you can call other templates for a complex hierarchy of template instantiation. The Base of template hierarchies are "Base-Templates" that produce the final data on the page. Here it is ottr:Triple and ax:SubClassOf.

Instantiate templates on normal pages, so that it produces triple instances on that page:

<ottr>
dpm:ExampleNamedPizza(dpm:ExamplePizza1, "Example"^^xsd:string).
</ottr>

Besides the normal literal syntax of the turtle and rdf grammar, the OTTR-syntax provides an easier literal definition for numbers (integers and floats) and booleans. Inside the subobjects they are written like normal string literals with a type hint.

The OTTR-language only provides argument passing via position and not via name.

The extension generates for every triple a subobject from the SMW Extension that contains the subject, predicate and object.

{{#subobject: |subject={{{1}}} |predicate={{{2}}} |object={{{3}}} |subobject-category=OTTR-Triple }}

Automated Forms

Generate forms (Page Forms extension) for the written OTTR templates, so that the information in the signature of the template (optional, default value, type etc.) is used to extend the input fields with the correct annoations. The extension generates a button for creating a new form page and prefills the needed code for the page inside the editor. For a more detailed description see #Automated_Forms and an example of the appearance of the button see here.

Overview Example

Templates instantiate other templates. Base templates are the fundament templates, that produces the triples (Here the ottr:Triple template). Example from the Pizza ontology [1] :

<ottr>
ex:NamedPizza[owl:Class ?pizza, ? owl:NamedIndividual ?country, NEList<ottr:IRI> ?toppings = (ex:TomatoSauce)] :: {
  ax:SubClassOf(?pizza, ex:NamedPizza),
  ax:SubObjectHasValue(?pizza, ex:hasCountryOfOrigin, ?country),
  ax:SubObjectAllValuesFrom(?pizza, ex:hasTopping, _:toppingsUnion),
  rstr:ObjectUnionOf(_:toppingsUnion, ?toppings),
  cross | ax:SubObjectSomeValuesFrom(?pizza, ex:hasTopping, ++?toppings)
} .
</ottr>

This example template from the OTTR-website uses different features (all implemented OTTR features are described in detail in the other sections):

• ?, marking a parameter/argument as optional and so the input can be set to none or ottr:none, so that the instances of the templates are executed otherwise the template does not produce any output if arguments (without the parameter option) have the value equal to none. (Another parameter option in the Non-Blank option !, that is also written in front of the argument name and an optional type restriction).
• _:toppingsUnion, blank nodes generate new IRIs (references) for every instance of the template without putting an explicit IRI inside the template (Non-Blank parameter option ! throws an error if the value of an argument is a blank node).
• cross | ... ++, list expand and list expander that handles different list behavior to instantiation of templates and triples with lists as arguments, so that every entry in a list gets an own instance. There is the cross (-product), ZipMin and ZipMax for multiple lists as arguments for an instance, that connects the entries of the different lists in nonidentical ways.
• owl:Class, NEList<ottr:IRI>, type check of the arguments. In this case to IRIs with the type of owl:class and inputs of not empty lists with entries of any IRI look. In the extension this feature is best working for literal types and Lists, but the type interference of the input needs some additional attention by the user.
• = (ex:TomatoSauce) default value such that if a none value is passed the default value is used. (Added inside this example for this documentation)

Instantiate Templates, that produce triples on the page.

<ottr>
ex:NamedPizza(ex:Margherita, ex:Italy, (ex:Mozzarella, ex:Tomato)) .
ex:NamedPizza(ex:Hawaii, none, (ex:Cheese, ex:Ham, ex:Pineapple)) .
</ottr>

Inside a media wiki, that handles such themes it would be, for example, plausible to write the first instance on the ex:Margherita and second on the ex:Hawaii, so that the information is stored on the correlated pages.

Subtemplates

A base template can be defined like here [2]:

<ottr>ottr:Triple [ ottr:IRI ?subject, ! ottr:IRI ?predicate, rdfs:Resource ?object ] :: BASE .</ottr>

Other templates that create rdf(s) relationships like subclasses, etc. (Often with a more complex triple call than just one call):

<ottr>
ax:SubClassOf[
    ottr:IRI ?subclass,
    ottr:IRI ?parentclass
] :: {
    ottr:Triple(?subclass, rdfs:subClassOf, ?parentclass)
} .
</ottr>

Implementation Details

The generated code is not saved on the page, like all normal parser tags. An exception is the usage of the #safesubst:ottrFunction, which replaces the call directly while the page saving process.

For more see Help:Extension:OttrParser