MatOnto Logo

MatOnto provides a decentralized, federated and distributed framework for the Materials Science Community to publish and discover data, data models, and analytics that are instantly consumable.

Introduction

MatOnto is a free and open platform which links native data sources into a semantic web, creating a vast knowledge-base for the Materials Science Community to accelerate discovery and deployment of advanced material systems. MatOnto is built with Apache Karaf and utilizes OWL 2 for authoring ontologies, the SPARQL query language for data lookup, and a pluggable backend system for processing and handling graph data modeled using the Resource Description Framework (RDF). The MatOnto framework applies the best practices recommended by the World Wide Web Consortium (W3C) to support organic growth of knowledge in the Materials Science Community.

Quick Start Guide

Installing from the Distribution

Prerequisites

MatOnto requires a Java SE 8 environment to run. Refer to http://www.oracle.com/technetwork/java/javase/ for details on how to download and install Java SE 1.8 or greater.

Make sure your JAVA_HOME environment variable correctly points to your Java 8 installation directory.

Installation

Download the appropriate binary distribution for your system using our download site.

The MatOnto distribution comes packaged as a .zip file for Windows and a tar.gz file for Linux/OSX. Extract this file to a new directory on your system. For example, in C:\MatOnto - from now on this directory will be referenced as MATONTO_HOME.

Open a command line console and change the directory to MATONTO_HOME.

To start the MatOnto server, run the following command in Windows:

> cd %MATONTO_HOME%
> bin\start.bat

or for Linux/OSX:

$ cd $MATONTO_HOME
$ ./bin/start

All MatOnto prepackaged bundles, services, and required artifacts and dependencies will be automatically deployed by the runtime once started.

The MatOnto web application should now be accessible at https://localhost:8443/matonto/index.html. The default login credentials are admin:admin.

User Guide

The MatOnto web application currently has four main modules:

The web application also has a My Account page to configure various settings and preferences of the logged in user and a User Management page for admin users to configure user accounts and groups. The Configuration for the MatOnto software itself is set in configuration files.

Ontology Editor

The MatOnto web-based ontology editor provides a Distributed Ontology Management System (DOMS) for local and community development of Web Ontology Language (OWL) ontologies. The DOMS features a customizable user interface, knowledge capture, collaboration, access policy management, ontology reuse, and extensibility.

To reach the ontology editor, click on the link in the left menu.

The Ontology Editor
Figure 1. The Ontology Editor

The initial view of the Ontology Editor shows the New Ontology Tab. The center pane displays a paginated list of all unopened ontologies in the local MatOnto repository. Each ontology in the list contains ontology metadata and a delete button. Deleting an ontology from this location will delete the ontology and associated ontology record and change history from the local catalog.

Clicking on an ontology in the list will bring up an overlay where you can select whether to open the ontology in the OWL ontology editor or SKOS vocabulary editor. The ontology editor features tools for creating full (OWL2) ontologies. The vocabulary editor features a select set of capabilities targeted at creating (SKOS) vocabularies.

When opening an ontology, the editor will load the previous branch and commit you were viewing. If you have not previously opened the ontology or the branch you were viewing no longer exists, then the editor will load the HEAD commit of the ontology’s master branch. For an explanation of commits and branches see the section on Ontology Versioning.

From this screen you can also filter the ontology list, create new ontologies, or upload existing ones.

Creating New Ontologies

To create a new ontology, select the New Ontology button on the main ontology editor view. In the creation dialog, you are required to provide an ontology IRI and title. You can also optionally provide a description and keywords. This metadata is used to describe the ontology in the local catalog.

new ontology form
Figure 2. New Ontology Form

The Ontology IRI is the unique identifier for the new ontology. The editor pre-populates this field with a default namespace and a local name generated from the Title field. You can always override this behavior. The Title field populates the dcterms:title annotations of both the new ontology record and the ontology object within the new ontology. The Description field populates the dcterms:description annotations of both the new ontology record and the ontology object within the new ontology. The Keywords field will attach the entered values as keywords to the new ontology record. The Open in radio buttons determine whether the new ontology will be opened in the ontology editor or the vocabulary editor.

Uploading Existing Ontologies

To upload an existing ontology, select the Upload Ontology button on the main ontology editor view. In the upload dialog, you are required to provide an ontology file and title. You can also optionally provide a description and keywords. This metadata is used to describe the ontology in the local catalog.

upload ontology form
Figure 3. Upload ontology form

Supported ontology file types are .owl, .ttl, .xml, .jsonld, .owx, and .rdf. The Title field populates the dcterms:title annotation of the new ontology record. The Description field populates the dcterms:description annotation of the new ontology record. The Keywords field will attach the entered values as keywords to the new ontology record. The Open in radio buttons determine whether the ontology will be created in the ontology editor or the vocabulary editor.

Editing an Ontology

The Ontology Editor provides an interface for developing OWL ontologies.

Note
To learn more about OWL ontologies, see the W3C Specification.

The Ontology Editor contains various tabs supporting activities for ontology development, search, and version control.

full editor ontology view
Figure 4. Ontology Editor

This section will describe the tools related to ontology development activities. These include:

For a detailed description of the versioning components, refer to the Ontology Versioning section.

Ontology Project Section

The Ontology Project Section displays high-level information about the ontology. This includes the ontology annotations and properties, ontology imports, and a preview of the serialized ontology RDF.

ontology editor section project
Figure 5. Ontology Editor Project Section

The top of this section contains the title of the ontology and its IRI. The IRI shown is the Version IRI, Ontology IRI, or a blank node identifier.

On the upper left side of this section is a block containing a list of all the applied OWL Ontology Properties and Annotations. There are controls included to add, remove, and edit these properties.

On the lower left side of this section is a block containing a list of all the ontology imports.

On the right of this section is a block used to generate a preview of the ontology as RDF. There is a drop down with several different RDF serializations to choose from. Clicking Refresh will generate a preview of the saved state of the ontology in the specified RDF format in the area below. Additionally, there is a button for downloading the ontology in several formats.

Note
The serialized ontology is a representation of data stored in the repository and will not include unsaved changes.
Overview Section

The Overview Section provides quick access to classes and their associated properties as compared to the Classes and Properties sections. Properties are associated to classes through the use of rdfs:domain.

ontology editor section overview
Figure 6. Ontology Editor Overview Section

The left side of this section contains the list of classes and their associated properties. Any properties that have no rdfs:domain are grouped into a folder in the hierarchy called "Properties". You can expand a class to view its properties by clicking the "+" icon or double-clicking the class name. Properties are displayed with a symbol representing the data type of the range property. Selecting an item in the tree will load that entity’s information into the other panels in this section.

The middle panels in this section allow you to add, remove, and edit Annotations and Axioms for the selected class or property.

The block on the right of the Overview Section displays all the locations where the selected entity is used within the saved state of the ontology. For classes, this is anywhere the selected class is used as the object of a statement. For properties, this is anywhere the selected property is used as the predicate or object of a statement. Usages are grouped by the predicate of the statement and can be collapsed by clicking on the predicate title. Links in the usages block, as with links in various other components of the editor, can be clicked to navigate to that entity.

Classes Section

The Classes Section allows you to view, create, and delete classes in the opened ontology.

ontology editor section classes
Figure 7. Ontology Editor Classes Section

The left side of the section contains a hierarchal view of the classes nested according to their rdfs:subClassOf property. That is, a class’s children are classes which are defined as subclasses of the particular class. Since classes can be defined as a subclass of multiple classes, they may appear several times within the hierarchy. Clicking on an item in the hierarchy will load that class’s information into the other panels in this section. Double clicking on a class with children will toggle the display of the children.

The middle panels in this section allow you to add, remove, and edit Annotations and Axioms for the selected class.

The block on the right of the Classes Section displays all the locations where the selected class is used within the saved state of the ontology. That is, anywhere the selected class is used as the object of a statement. Usages are grouped by the predicate of the statement and can be collapsed by clicking on the predicate title. Links in the usages block, as with links in various other components of the editor, can be clicked to navigate to that entity.

Properties Section

The Properties Section allows you to view, create, and delete properties in the opened ontology.

ontology editor section properties
Figure 8. Ontology Editor Properties Section

The left side of the section contains a hierarchal view of the datatype and object properties. The datatype and object properties are grouped into two separate folders within the hierarchy that will open and close when clicked. Properties are nested according to their rdfs:subPropertyOf property. That is, a property’s children are properties which are defined as subproperties of the particular property. Properties are displayed with a symbol representing the data type of the range property. Clicking on an item in the hierarchy will load that property’s information into the other panels in this section. Double clicking on a property with children will toggle the display of the children.

The middle panels in this section allow you to add, remove, and edit Annotations and Axioms for the selected property.

To add a property, click Create Property and use the overlay to configure the new property. The gray text at the top of the overlay is the new property’s IRI. It is pre-populated with the ontology IRI and will be filled in with the value in the Name field. To edit this IRI, click the pencil button next to the IRI. The Name field will populate the dcterms:title annotation. The Type field allows you to select whether you are creating an object or datatype property. The Description field will populate the dcterms:description annotation. The Domain field sets the rdfs:domain axiom. The Range field sets the rdfs:range axiom. The available values in the Range field will change depending on whether you are creating an object or datatype property.

create property overlay
Figure 9. Create property overlay

The third block on the right of the Properties Section displays all the locations where the selected property is used within the saved state of the ontology. That is, anywhere the selected property is used as the predicate or object of a statement. Usages are grouped by the predicate of the statement and can be collapsed by clicking on the predicate title. Links in the usages block, as with links in various other components of the editor, can be clicked to navigate to that entity.

Individuals Section

The Individuals Section allows you to view, edit, create, and delete individuals in the opened ontology.

ontology editor section individuals
Figure 10. Ontology Editor Individuals Section

The left side of the section contains a view of all individuals nested under their classes based on the rdfs:subClassOf property. Clicking on an item in the list will load that individual’s information into the other panels in this section.

The panels to the center and right of the section allow you to add, remove, and edit Data, Object, and Annotation Properties for the selected individual. The options for Data and Object Properties are populated from the ontology and its imports.

Search Section

The Search Section allows you to perform a keyword search through all the entities within the saved state of the opened ontology.

ontology editor section search
Figure 11. Ontology Editor Search Section

The left side of the section contains a simple search bar and a list of search results. To perform a search, type a string into the search bar and press the ENTER key. The results are separated by type and each category is collapsible. Each result is displayed with its display name. Properties are displayed with a symbol representing the data type of the range property. Clicking on a result will load that entity’s information into the other panels in this section. Double clicking on an entity will open that entity in the appropriate tab.

The right panel of the section displays all the properties of the selected entity. The parts of the property values that match the search text will be highlighted.

Editing a Vocabulary

The Vocabulary Editor provides tools to edit all aspects of an opened ontology as a SKOS vocabulary.

Note
To learn more about SKOS vocabularies, see the W3C Specification.

There is one section unique to the vocabulary editor for editing different aspects of a SKOS vocabulary: the Concepts Section.

The Project, Search, Saved Changes, Merge, and Commits sections behave the same as in the Ontology Editor. Vocabulary versioning works the same as for ontologies, and is described in the Ontology Versioning section.

full editor vocabulary view
Figure 12. Vocabulary Editor
Concepts Section

The Concepts Section displays information about all the concepts and concept schemes defined in the opened vocabulary.

vocabulary editor section concepts
Figure 13. Vocabulary Editor Concepts Section

The left side of the section contains a hierarchal view of the concept schemes and concepts. The top level items are the concept schemes and their children are all concepts within that scheme. This could be defined through the skos:hasTopConcept property, the skos:inScheme property, or determined transitively. The concept hierarchy is determined using all of the SKOS broader and narrower properties. Clicking on an item in the hierarchy will load that concept scheme’s or concept’s information in the other panels in this section. Double clicking on a concept scheme or concept with children will toggle the display of the children.

The middle panels in this section allow you to add, remove, and edit Annotations and Relationships for the selected property.

The third block on the right of the Concepts Section displays all the locations where the selected concept scheme or concept is used within the saved state of the vocabulary. This is anywhere the selected concept scheme or concept is used as the object of a statement. Usages are grouped by the predicate of the statement and can be collapsed by clicking on the predicate title. Links in the usages block, as with links in various other components of the editor, can be clicked to navigate to that entity.

Ontology Versioning

Each ontology or vocabulary in MatOnto is versioned in a manner similar to the Git Version Control System, whereby all changes to an ontology/vocabulary are collected into a chain "commits" which form a commit history called a "branch". Thus, every version in the history of an ontology/vocabulary can be generated by selecting a commit and applying all the changes in the branch back to the initial commit.

Every ontology is initialized with a MASTER branch that contains the initial commit. Work can be done on this MASTER branch or can be split out into separate branches. Work done on these branches occur in isolation until they are merged back into the MASTER branch, joining any other changes committed in the meantime. When merging two branches, the ontology editor does its best to combine any changes made on both branches. If a conflict occurs, the editor allows the user to resolve them manually. More information on merging branches can be found in the section on Merging Branches.

Managing Branches

The Branch Select Box, located in the upper-left corner of the opened ontology, provides a list of all the available branches for editing. To checkout a branch, simply select the branch in the drop-down menu. Note that the branch selection will be disabled if you have any uncommitted changes on the current branch. To edit a branch name or description, click on the edit icon next to the branch in the drop-down menu. You cannot edit the master branch of an ontology or vocabulary.

branch select
Figure 14. Branch select box

To delete a branch, click on the delete icon next to the branch in the drop-down menu. If a branch is deleted, all commits on that branch that are not part of another branch will be removed, as well as the branch itself. Note that this action cannot be undone.

Viewing Saved Changes

The Saved Changes Section displays all saved and uncommitted changes in the opened ontology or vocabulary. Saving changes without committing allows a user to edit an ontology through a number of browser sessions before making any commits to the commit history. These changes are unique to the user, and are available to other users once a commit is performed.

ontology editor section saved changes
Figure 15. Ontology Editor Saved Changes Section

Within each entity IRI in the list are the added and deleted triples for each ontology entity. If there are no saved changes to the ontology or vocabulary, this page will be empty. To commit these changes, select the Commit Saved Changes button in the Button Stack. To remove these saved changes, select the Delete Saved Changes button in the Button Stack.

If new commits have been made to the branch by other users while you are editing or viewing an ontology, a warning symbol will be displayed in the section title and a message will be displayed in the section notifying you that there are new commits on the branch. If you have no saved changes, there will be a link to update the current ontology by pulling in the latest changes.

pull latest changes
Figure 16. Pull in latest changes message
Merging Branches

The Merge Section allows you to merge the head commit of the branch you are currently viewing into the head commit of another branch. Two branches can only be merged if there are no conflicts between the head commits of each branch. The merge form displays the name of the current branch (Source), a select box for the branch you want to merge into (Target), and a checkbox for whether or not you want the Source branch to be deleted after it is merged.

merge section
Figure 17. Merge branches form

Clicking Submit will attempt to perform the merge. If there are no conflicts between the changes on both branches, the form will reset, a commit will be created connecting the two branches, and a success message will appear in the top right corner of the screen.

If there are conflicts that prevent the editor from merging the two branches automatically, the merge process will be halted and the screen will update to notify you of those conflicts and provide you a way to resolve them. Each conflict is listed by entity within the ontology or vocabulary and with a marker indicating whether or not it has been resolved. Click on a conflict in the list to start resolving them.

merge conflicts main
Figure 18. List of all merge conflicts

When resolving a conflict, the tool displays the changes to the entity from both branches. To resolve the conflict, select the version of the entity you wish to keep. You can either click the Back to List button to go back to the list of all the conflicts or the Previous or Next buttons to iterate through the list of conflicts.

Note
Currently the editor only supports accepting entire changes. We are working on improvements to give more flexibility in resolving conflicts during a merge operation.
merge conflicts resolution
Figure 19. Merge conflict resolution screen

Once all conflicts have been resolved, the Submit with Resolutions button will become active and you can complete the merge operation. Completing the merge will create a new commit that incorporates your conflict resolutions into the target branch, resets the form, and displays a success message in the upper right corner of the screen.

Commits Section

The Commits Section provides a table of all the commits made in the history of the branch you are currently viewing. The username of the creator, ID, message, and date for each commit are displayed within the table.

Note
We are currently working on an improved visualization of the commit history. Expect a better experience in release 1.5!
commit history table
Figure 20. Commit history table of a branch

Ontology Editor Reference

Edit IRI Overlay

The Edit IRI overlay provides the user with a simple way to edit and create valid IRIs. The Begins with field (required) is the beginning of the IRI. This is more commonly known as the namespace. When editing the IRI of entities within an ontology, this value is typically the ontology IRI. The Then field (required) is the next character in the IRI. This value can be thought of the separator between the namespace and local name (described below). The provided values for the Then field are "#", "/", and ":". The Ends with field (required) is the last part of the IRI. This value is commonly known as the local name. It is used in the drop down lists in this application as the easiest way to identify what the IRI references. Clicking the refresh button on the left will reset the three fields to their original values. Clicking Cancel will close the overlay. Clicking Edit will save the IRI with the entered values for the selected entity and update the ontology.

edit iri overlay
Figure 21. Edit IRI overlay
Property Value Displays

Property Value Displays are a common way MatOnto displays multiple values for a property on an entity. These properties could be datatype properties, object properties, annotations, axioms, etc. The display consists of the title section and the values section. The title section includes a bold title, the property IRI, and a toggle button for collapsing and expanding the values section. The values section lists all the values set for the displayed property along with the type, if the value is a literal, and edit and delete buttons. The functionality of the edit and delete buttons for values differ depending on where the Property Value Display is being used. If a value of a property is a property, class restriction, or expression, it will be represented in a simplified format that is easier to read. However, those values will not be able to edited or deleted.

Note
See the W3C Specification for information about blank nodes, class/property restrictions, and class/property expressions.
property value display
Figure 22. A property value display with multiple values
Button Stack

The Button Stack is visible in any Ontology or Vocabulary tab in the bottom right hand corner of the screen and holds a variety of buttons that are shown when the stack is hovered over.

button stack
Figure 23. Collapsed button stack

If a change is made to a ontology or vocabulary, the Save Changes button will become active. Clicking on this button saves changes to the opened ontology. More info on saving changes in the Viewing Saved Changes section.

save changes button
Figure 24. Save button
save changes overlay
Figure 25. Save changes overlay

If you have saved changes to an ontology or vocabulary, the Commit Saved Changes button will become active. Clicking on this button will bring up the Add Commit overlay.

commit saved changes button
Figure 26. Commit button

The Add Commit overlay provides a textarea for you to enter in a Message that will be associated with that commit. This commit usually specifies what changes where made in the commit so that others can read the message and understand what happened at that point in time. If the commit you were viewing is not the head commit of the current branch, there will be a message at the top of this overlay notifying you that committing your changes will create a new branch off of the current commit. This preserves the history of the branch while still allowing you to commit your work. This new branch will have the same title as the branch you were viewing, but with "WIP:" in at the beginning and will only be able to be merged back into the original branch. Clicking Cancel will close the overlay. Clicking Submit will add all your saved changes to a new commit object whose parent is the commit you were viewing and close the overlay.

add commit overlay
Figure 27. Add commit overlay
add commit overlay message
Figure 28. Add commit overlay with message

If you have saved changes to an ontology or vocabulary, the Delete Saved Changes button will become active. Clicking on this button will bring up a confirmation overlay for whether or not you want to revert all your saved changes. More info on saved changes in the Viewing Saved Changes section.

delete saved changes button
Figure 29. Delete saved changes button
delete saved changes overlay
Figure 30. Delete saved changes overlay

The Create Branch button allows you to create a new branch from the current commit and branch you are viewing on. This action can be performed even if you have unsaved or saved changes. Clicking on the button will bring up the Create New Branch overlay.

create branch button
Figure 31. Create branch button

The Create New Branch overlay provides fields for entering information about the branch as a whole. The Title field (required) will set the dcterms:title of the branch. The Description field will set the dcterms:description of the branch. Clicking Cancel will close the overlay. Clicking Submit will create a new branch with the entered information whose head commit was the commit you were viewing and close the overlay.

create branch overlay
Figure 32. Create new branch overlay

Mapping Tool

The MatOnto web-based Mapping Tool allows users to define custom, ontology-driven definitions to control and execute input data transformations to the Resource Description Framework (RDF) semantic data model. User-defined mappings load semantic data into the MatOnto store for analysis, sharing and linking.

To reach the Mapping Tool, click on the link in the left menu.

mapping tool link
Figure 33. Mapping Tool button

To use the Mapping Tool to map data, an ontology must be in the MatOnto repository, but it does not have to be opened to access it. If there are no available ontologies, you will not be able to map delimited data. To upload an ontology go to the Ontology Editor and follow the steps for uploading ontologies or creating a new ontology.

There are three main pages of the Mapping Tool:

The processes for creating, editing, and running a mapping all lead you to the File Upload Page.

Mapping Select Page

The Mapping Select Page provides functionality to manage mappings saved in MatOnto and utilize them. It contains a Mapping List and a Mapping Preview.

Mapping List

The Mapping List displays all the mappings currently saved in MatOnto and provides functionalities for creating and deleting mappings. Clicking on a mapping in this list will load the mapping into the Mapping Preview.

mapping list
Figure 34. Mapping list

Once you have selected a mapping, clicking on Delete Mapping will bring up a confirmation overlay for whether or not you actually want to delete mapping.

delete mapping overlay
Figure 35. Delete mapping overlay

Clicking on Create Mapping will bring up the Create Mapping overlay with initial setup options for the new mapping. First you must provide a new unique name for the mapping and then you can select whether the new mapping should be made from scratch or using a saved mapping as a template by selecting the appropriate radio button. Clicking on Cancel will bring you back to the Mapping Select Page. Clicking Continue will bring you to the File Upload Page to continue the process of creating a mapping.

create mapping overlay
Figure 36. Create mapping overlay
Mapping Preview

The Mapping Preview provides a preview of the selected mapping from the Mapping List along with actions to perform against the selected mapping. The preview includes the source ontology that was selected for the mapping and a list of all the mapped classes and their mapped properties within the mapping. Every mapping has a specified source ontology where all its class and property mappings stem from. The mapped datatype properties display the column index they are mapped to for quick reference.

mapping preview
Figure 37. Mapping preview

If the source ontology selected for the mapping no longer exists within MatOnto, an error message will be shown.

missing ontology message
Figure 38. Missing ontology message

There are three action buttons in this area that can be performed against the selected mapping. Those actions are editing a mapping, running a mapping, or downloading a mapping. The first two actions cannot be used if the source ontology no longer exists in MatOnto.

Clicking Run or Edit will perform a quick check to see if the source ontology or its imported ontologies changed in such a way that the mapping is no longer valid. If this check does not pass, an overlay will be shown informing you of the error. If the check for validity of the source ontology and its imports passes, you will be brought to the File Upload Page to continue either the process of either editing the mapping or running the mapping.

invalid ontology overlay
Figure 39. Invalid source ontology overlay

Clicking Download will bring up the Download Mapping overlay where you can select the RDF serialization for the mapping and download a copy of the mapping in RDF to your machine.

download mapping overlay
Figure 40. Download mapping overlay
Note
To learn about the structure of a mapping, refer to the MatOnto Mappings Appendix.

File Upload Page

The File Upload Page provides functionality for uploading a delimited file into MatOnto to be used when editing, creating, or running a mapping. There are two sections to the page:

These two sections behave slightly differently if you are running or editing a mapping.

File Upload Form

The File Upload Form contains a form for uploaded a delimited file along with different information depending on whether you are running or editing a mapping. Here you can choose a delimited data file, check whether or not the file contains a header row, and select the separator character if the file is CSV. The accepted file formats are .csv, .tsv, .xls, and .xlsx. Any changes to this form will automatically update the File Preview Grid.

If you are running a mapping, a preview of the mapping with the source ontology and mapped classes and properties will be shown. If the chosen delimited file does not contain enough columns for the mapping’s datatype property mappings, the properties in the mapping preview will appear red and you will not be able to run the mapping. Clicking Run at the bottom of the section will map the uploaded delimited data using the selected mapping and download the mapped data to your machine in JSON-LD RDF format.

file upload run
Figure 41. File upload form when running a mapping

If you are editing or creating a mapping, a preview of the mapping will not appear below the form. However if the chosen delimited file does not contain enough columns for the mapping’s datatype property mappings, a list of the missing columns will be displayed. However, you can still edit the mapping as long as those datatype properties are fixed. Clicking Continue or Fix at the bottom of the section will bring you to the Edit Mapping Page. If you are creating a mapping, the Mapping Configuration overlay will automatically open to get you started setting up the new mapping.

file upload edit
Figure 42. File upload form when editing/creating a mapping

Whether you are editing, running, or creating a mapping, clicking Cancel in the upload form section will bring up a confirmation overlay for whether or not you want to cancel the mapping process.

cancel mapping overlay
Figure 43. Cancel mapping confirmation
File Preview Grid

The File Preview Grid a preview of the first 50 rows of the uploaded delimited data. If you have selected that the first row is a header row in the File Upload Form, the first row of the data will be styled differently. If you are running a mapping, all the columns that will be mapped will be highlighted as well.

preview grid
Figure 44. File preview grid with highlights and a header row

Edit Mapping Page

The Edit Mapping Page contains all the functionality needed for creating and editing a mapping. There are two main sections to the page:

The File Preview Grid functions the same as it did in the File Upload Page.

Edit Mapping Form

The Edit Mapping Form contains two tabs with different forms. Both tabs contain three buttons at the bottom. Clicking Cancel will bring up a confirmation overlay for wheter the mapping process should be canceling. Any changes made to the mapping will not be saved if you cancel. Clicking Save will save the current state of the mapping to MatOnto and take you back to the Mapping Select Page. Clicking Save & Run will save the current state of the mapping to MatOnto, map the uploaded delimited data using the mapping, download the mapped data to your machine in JSON-LD RDF format, and then take you back to the Mapping Select Page.

edit mapping form
Figure 45. Edit mapping form

The first tab, "Edit", contains two different sections:

The second tab, "Preview", contains the RDF Preview Form.

Mapping Configuration

The Mapping Configuration section displays the basic configuration for the mapping including the title of its source ontology and the name of its base type. The base type of a mapping signifies the main class represented by each row in the delimited data. For example, you could have delimited data where each row represents a Person.

mapping config section
Figure 46. Mapping configuration section

To edit this configuration, click the pencil button next to "Configuration" and the Mapping Configuration overlay will appear where you can select the source ontology for the mapping and select a class for the base type. The Ontology drop down contains all the ontologies saved in the MatOnto repository. To search for an ontology, begin typing part or all of the ontology IRI/label. Once an ontology has been selected, a preview of the ontology, its imports, and its classes will appear and the Base Type drop down will populate with all the classes in the selected ontology and in all the ontologies in its imports closure. To search for a class, begin typing part or all of its IRI/label. Once a class has been selected, a preview of the class and all the available properties that can be set for it will appear. These properties include all properties in the selected ontology and its imports that either defined the class as a domain or have no domain set. Clicking Cancel will close the overlay. Clicking Set will set this new configuration for the mapping. Changing the configuration of a mapping will remove any class mappings that have been set in the mapping.

mapping config overlay
Figure 47. Mapping configuration overlay
Class Mapping Navigation

The Class Mapping Navigation section allows you to edit the different class mappings and their property mappings within the mapping. Every class mapping in a mapping declares that an instance of that class will be created for each row. The Class Mapping drop down allows you to select which class mapping to view along with a button for deleting the selected class mapping.

class mapping select
Figure 48. Class mapping drop down

Clicking on the delete button will bring up a confirmation overlay for whether or not the class mapping should be deleted. If you delete a class mapping that an object property mapping links to, that property mapping will be deleted as well.

delete class mapping overlay
Figure 49. Delete class mapping overlay

Once you have selected a class mapping, the area below will display details about the class mapping. It will display the IRI template for the class mapping which the template MatOnto will use when creating IRIs for the created class instances from this class mapping. The value within the ${} indicates what will be used for the local name of each class instance’s IRI. "UUID" means that a unique identifier will be generated for each class instance. An integer means that MatOnto will grab the value from the column with that index (zero-based) for each row and use each value as the local name for the class instance.

iri template
Figure 50. IRI template display

To edit this template, click the pencil button next to "IRI Template" and an overlay will appear with settings to change this template. The Begins With field contains the static beginning of the IRI template along with space to add more. The default is the name of the class mapping itself. The concatenation of the static beginning and the value in the field are commonly known as the namespace of an IRI. The Then drop down contains options for the next character in the IRI template. The options are "/", "#", and ":". This character can be thought of as the separator between the namespace and the local name (described below). The Ends With field is where you select the dynamic value for the end of the IRI template. Clicking Cancel will close the overlay without making any changes. Clicking Set will change the IRI template for that class mapping.

iri template overlay
Figure 51. IRI template overlay

Selecting a class mapping will also display all the property mappings set for that class mapping. Every instance of the class the class mapping creates will have a property with a value as defined by a property mapping. To create a new property mapping, click Add Property and the Property Mapping overlay will appear.

add prop btn
Figure 52. Add property button

In this overlay, the Property drop down contains all the properties from the source ontology and its imports that explicitly state the class mapping’s class as a domain or that have no domain set. If you select a datatype property, the Column drop down will appear with column headers from all the columns that have not been mapped yet. The property mapping will pull the value in that column for each row as the value of the property for the class instance. Clicking Set will create a datatype property mapping for the selected class mapping with the selected column as its value. All columns are saved by their zero-based index in the mapping.

add data prop mapping
Figure 53. Adding a datatype property mapping

If you select an object property, you will see a description of the class that property links to in its range. Clicking Set will create an object property mapping for the selected class mapping and a new class mapping for the class the property links to.

add object prop mapping
Figure 54. Adding a object property mapping

Every property mapping in the list will display what value it will be pulling. For datatype property mappings, it will display the name of the column it will collect data from. For object property mappings, if will display the name of the class mapping it links to. Double clicking on an object property mapping will open the class mapping it links to. Clicking on a datatype property mapping will highlight the column it links to in the File Preview Grid. If any of the datatype property mappings are invalid, meaning the index they point to does not exist in the delimited data, they will appear as red.

prop mappings list
Figure 55. Property mappings list

To edit a property mapping, click on the pencil button for that property and the Property Mapping overlay will appear to edit the value of the property. Clicking on the delete button for a property will bring up a confirmation overlay for whether or not that property mapping should be deleted from the selected class mapping.

delete prop mapping overlay
Figure 56. Delete property mapping overlay
RDF Preview Form

The RDF Preview Form allows you to create a preview of what the uploaded delimited data would look like mapped with the current state of the mapping. The Serialization drop down contains several RDF serializations in it and clicking Refresh will display the results from the first 10 rows of the delimited data in the specified RDF format.

rdf preview form
Figure 57. RDF preview form with a preview

SPARQL Editor

The MatOnto web-based SPARQL editor allows users to formulate and execute queries of semantic data. Users can save, publish, share and reuse their SPARQL queries as part of applications or larger workflows.

Tip
To learn more about SPARQL queries, see the W3C Specification.

To reach the SPARQL Edtior, click on the link in the left menu.

sparql editor link
Figure 58. SPARQL Editor link

There are two main sections of the SPARQL Query Editor:

Query Editor

The Query Editor contains the Prefixes field, a text area to enter a SPARQL query, and a Submit button. The Prefixes field contains a list of standard prefixes for commonly used ontologies. When selected, a prefix can be used within the text area when creating a SPARQL query. Selected prefixes will not be used in the Query Results display.

query editor
Figure 59. Query Editor with a prefix selected

Clicking Submit will execute the entered query against the MatOnto repository and update the Query Results section with the results.

Query Results

The Query Results section will show the results of your last SPARQL query against the MatOnto repository in a table format along with how many results were found and the current page number. Only one hundred lines of results will be shown at a time. If there are more than one hundred results from your last query, then pagination buttons to go to the previous and next pages of results will appear on either side of the current page number.

pagination buttons
Figure 60. Pagination Buttons

The table of query results will be generated based on the structure of the SPARQL query in the Query Editor. The headers of the table will be the variables specified in the SPARQL query. Each row of the table represents a single RDF triple.

query with three variables
Figure 61. Sample query with three variables
results with three variables
Figure 62. Results of the query with three variables

Catalog

The MatOnto web-based Catalog allows users to publish data, dataset descriptions, analytics and other resources. It allows users to control the way their data is shared. MatOnto catalogs join in a federated architecture and share resources based on defined policy.

To reach the Catalog click on the link in the left menu.

catalog link
Figure 63. Catalog button

Each MatOnto node has access to two catalogs: the Local catalog and the Distributed catalog. The Local Catalog contains all unpublished Records contained with your MatOnto node including any versioned ontologies created in the Ontology Editor. The Distributed Catalog contains Records published by other MatOnto nodes based on their policies. Each catalog is accessible through a tab near the top of the Catalog.

Note
Distributed Catalog coming soon!
catalog tabs
Figure 64. Catalog Tabs

Within both catalog tabs, you can navigate through the Records and their sub-entities to view metadata about each entity. Each entity can be opened into its own page:

Each page contains the Record Search Bar at the top of the page to search through the Records within the current Catalog.

At the top of each page is the Record Search Bar which contains a filter drop down, a text input, and a "Search" button. The filter drop down contains all possible types of Records. The text box allows you to perform a text search through all the Record metadata. To submit a search, click Search and the list in the Catalog Page will update and begin at the first page of the new results list. This search bar is present on all the pages so clicking Search will automatically bring you back to the Catalog Page. The filter selection and search text are saved on a per catalog basis and will persist even when navigating throughout MatOnto.

search bar
Figure 65. Catalog Search Bar

Catalog Page

The Catalog Page displays all the Records within the current catalog that match the search criteria in the Record Search Bar in a paginated list that can be sorted. The header section contains a breadcrumb trail of the entities you have opened within the current catalog. On the Catalog Page, this will only contain the title of the current catalog.

catalog page header
Figure 66. Catalog Page header section

The main body of the Catalog Page contains the results of most recent search executed in the Record Search Bar. At the top, it displays the number of Records in the current page, the total number of Records that matched the search, and a drop down containing sort options based on different metadata points. These options are the issued date, the modified date, and the title and can be sorted in the ascending or descending direction.

catalog page pagination header
Figure 67. Catalog Page count and sort options

The rest of the main body contains the list of matching Records. Each entry displays the title, issued date, modified, description, and keywords of the Record. The description display can be toggled to display a preview or the full description. In the top right of each entry is a color coded list of the associated types of the Record for easy recognition. Clicking on a Record entry will bring you to the associated Record Page. At the bottom of the Catalog Page is pagination buttons for navigating through the results of the most recent search.

catalog page records list
Figure 68. Catalog Page records list

Record Page

The Record Page displays all metadata for the associated Record along with a paginated list of any sub-entities. The header section contains a breadcrumb trail of the entities you have opened within the current catalog and the title of the associated Record. On the Record Page, the breadcrumb will contain a link to the current Catalog and the title of the associated Record.

record page header
Figure 69. Record Page header section

The main body of the Record Page contains all the metadata about the associated Record and a paginated list of any sub-entities of the Record. The metadata shown includes the issued date, modified date, full description, and keywords. It also displays the color coded list of associated types for the Record.

record page metadata
Figure 70. Record Page metadata

The paginated list of sub-entities will differ depending on the type of the associated Record and may not be shown at all. The list, if present, can be sorted based on the issued date, modified date, and title and can be sorted in the ascending or descending direction. If there is a list of sub-entities, the bottom of the Record Page will have pagination buttons for navigating through the list. For example, if the Record is a VersionedRDFRecord, the list of Branches for that Record will be shown. Each entry displays the title, issued date, modified date, and description of the associated Branch. The description display can be toggled to display a preview or the full description. Clicking on a Branch entry will bring you to the associated Branch Page.

record page branches list
Figure 71. Record Page branches list

Branch Page

The Branch Page displays all metadata for the associated Branch. The header section contains a breadcrumb trail of the entities you have opened within the current catalog and the title of the associated Branch. On the Branch Page, the breadcrumb will contain a link to the current Catalog, a link to the parent Record, and the title of the associated Branch.

branch page header
Figure 72. Branch Page header section

The main body of the Branch Page contains all the metadata about the associated Branch. The metadata shown includes the issued date, modified date, full description, and id of the head Commit for the associated Branch.

branch page metadata
Figure 73. Branch Page metadata

My Account

The My Account page of MatOnto provides users with a way to configure their own account and customize various aspects of the application to suit their needs.

To reach the My Account page, click on the gear in the top right corner of the application and select My Account.

my account link
Figure 74. My Account link

The My Account page contains two main sections for configuring your account:

my account tabs
Figure 75. My Account tabs

Profile

The Profile section contains a form for viewing and editing your basic profile information. This information includes your First Name, Last Name, and Email address. None of this information is required. Your current settings for these fields will be displayed to start. To edit, simply change the values in one or more of the fields and and click Save in the bottom right. If the change was successful, you will see a success message at the top of the section.

profile
Figure 76. Profile page
profile success
Figure 77. Successful profile change

Password

The Password section contains a form for updating your password. To change it, you must first input your Current Password in the first field. Then enter your desired New Password in the second field and the Confirm Password field and click Save in the bottom right. If the change was successful, you will see a success message at the top of the section.

password
Figure 78. Password page
password success
Figure 79. Successful password change

User Management

The User Management page provides administrators with a portal to create, edit, and remove users and groups in MatOnto.

To reach the User Management page, click on the gear in the top right corner of the application and select User Management.

user management link
Figure 80. User Mangement link

This page will be read-only for users without the admin role. There are two main sections of the User Management page:

user management tabs
Figure 81. User Management tabs

Groups

The Groups page allows you to create, edit, and remove groups from the application. Groups allow you to associate users with one another and apply the same permissions and roles to all members. The left side of the section contains a list of all the groups in MatOnto. Next to each group title is an indicator of how many users are within that group. At the top of the list is a search bar that will filter the list of groups based on their title. Clicking on a group title will load that group’s information into the right side of the section.

groups list
Figure 82. Groups list

To create a group, click Create Group and the Create Group overlay will appear. The Group Title field (required) allows you to specify a name for the group. The Description field allows you to enter in a description about what the group represents. At the bottom of the overlay is a table for adding users to the group. Your user account will be added automatically. To add others to the group, click Add Member and that line in the table will transform into a drop down selector of all the users in MatOnto that have not already been selected. To remove a user from the table, click on the corresponding delete button at the end of the row. Clicking Cancel will close the overlay. Clicking Add will create a new group with the entered information and add the listed users to it.

create group overlay
Figure 83. Create group overlay

Clicking Delete Group after selecting a group in the list will bring up a confirmation overlay for whether or not that group should be removed from MatOnto.

delete group overlay
Figure 84. Delete group overlay

At the top of the right side of the section is the title of the selected group.

group title
Figure 85. Title in the group section

Below the group title are several blocks. One block displays the description for the selected group.

group description block
Figure 86. Group description block

To edit the selected group’s description, click Edit and the Edit Group Description overlay will appear. The overlay contains a text field for editing the group’s Description. Clicking Set will update the selected group’s description with the entered value. Clicking Cancel will close the overlay.

edit group description overlay
Figure 87. Edit group description overlay

The other block in the right side of the section displays a table of the group’s members. To add another user to the group, click Add Member and that line in the table will transform into a drop down selector of all the users in MatOnto that have not already been selected. Selecting a user in this drop down will automatically add them to the group. To remove a user from the table, click on the corresponding delete button at the end of the row. Any changes in this table will immediately be applied.

group member block
Figure 88. Group member table block

Users

The Users page allows you to create, edit, and remove users from the application. The left side of the section contains a list of all the users in MatOnto. If a user is an administrator, whether by the having the admin role or by being a part of a group with the admin role, an indicator will be next to their username in the list. At the top of the list is a search bar that will filter the list of users based on their username. Clicking on a username will load that user’s information into the right side of the section.

users list
Figure 89. Users list

To create a user, click Create User and the first of the Create User overlays will appear. At the bottom of each of the Create User overlays is a progress indicator of which step you are currently on and how many more there are. The first overlay contains fields for entering basic information about the user. The Username field (required) must be unique within the application. The Password fields (required) allow you to enter in the password for the new user. The other three fields, First Name, Last Name, and Email, are not required, but allow you to enter in basic profile information for the new user. Clicking Cancel will close the overlay. Clicking Next will bring you to the next Create User overlay.

create user overlay 1
Figure 90. First create user overlay

The second Create User overlay contains fields for the new user’s permissions. Currently, you can only set whether or not the new user is an administrator with the provided checkbox. Clicking Back will bring you back to the first Create User overlay. Clicking Add will create a new user with the entered information in both overlays.

create user overlay 2
Figure 91. Second create user overlay

Clicking Delete User after selecting a user in the list will bring up a confirmation overlay for whether or not that user should be removed from MatOnto.

delete user overlay
Figure 92. Delete user overlay

At the top of the right side of the section is the username of the selected user.

username
Figure 93. Username in the users section

Below the username are several blocks. One block displays the profile information for the selected user. Clicking on the email address of the user will attempt to begin an email to that address using your machine’s default email engine.

user profile block
Figure 94. User profile block

To edit the selected user’s profile information, click Edit and the Edit User Profile overlay will appear. The overlay contains three fields: First Name, Last Name, and Email. None of the fields are required. Clicking Cancel will close the overlay. Clicking Set will update the selected user’s profile information with the entered values.

edit user profile overlay
Figure 95. Edit user profile overlay

Another block in the right side of the section provides a button to change the selected user’s password.

change password block
Figure 96. Change password block

Clicking on Change Password will bring up the Change Password overlay. You must provide the selected user’s Current Password in order to change it. Next, enter in the desired New Password and Confirm Password as well. The values in the New Password and Confirm Password fields must match. Clicking Cancel will close the overlay. Clicking Set will change the selected user’s password to the entered password as long as the value in the Current Password field matches the user’s saved password.

change password overlay
Figure 97. Change password overlay

Another block in the right side of the section displays the selected user’s permissions and roles. Changing any of the values of the checkboxes in the block will automatically update the selected user’s permissions or roles.

permissions block
Figure 98. Permissions block

The last block in the right side of the section displays the selected user’s groups as a list of links. Clicking on the title of a group will open it in the Groups section.

user groups block
Figure 99. User groups block

Configuration

All default configuration files for Apache Karaf and MatOnto are located inside the {MATONTO_HOME}/etc directory.

MatOnto

Service Configuration

The basic MatOnto services can be configured using the following files:

Table 1. MatOnto Service Configuration Files
Configuration File Description

org.matonto.catalog.api.CatalogManager.cfg

Configurations for the MatOnto Catalog Manager

org.matonto.etl.api.MappingManager.cfg

Configurations for the MatOnto Mapping Manager

org.matonto.ontology.core.OntologyManager.cfg

Configurations for the MatOnto Ontology Manager

org.matonto.platform.config.state.StateManager.cfg

Configurations for the MatOnto State Manager

org.matonto.service.repository.native-system.cfg

Configurations for the MatOnto System Repository

By default, all resources are stored in the system repository which is an RDF triplestore located in the data/repos/system directory of the MatOnto distribution. Each repository in MatOnto is uniquely identified by its id. To change the data location, id, or title of the system repository, edit the dataDir, id, and title properties respectively in the org.matonto.service.repository.native-system.cfg file. Apache Karaf will dynamically reload any changes made to this existing file.

You can create new repositories to be used for storage in MatOnto. First, choose either a "native" repository or a "memory" repository. These two types of repositories are defined in the NativeRepositoryConfig and MemoryRepositoryConfig classes in the org.matonto.repository.impl.sesame module. Once you have chosen the type of repository, make a new .cfg file in the {MATONTO_HOME}/etc directory with a file name that starts with either "org.matonto.service.repository.native" or "org.matonto.service.repository.memory". In the file, set the id, title, and dataDir properties you wish for the repository. The file should look like this:

id=demo
title=Demonstration
dataDir=path/to/directory

Apache Karaf will automatically recognize the new configuration file and create the new repository.

To change which repository the Catalog, Mapping, Ontology, and State resources are stored into, open the associated .cfg file and change the id of the repository.target property to be the id of the new repository. For example to change the repository for storing Catalog resources to the repository created above, you would open the org.matonto.catalog.api.CatalogManager.cfg file and edit the repository target line to be:

repository.target = (id=demo)

Apache Karaf will automatically detect the changes and reload the new configuration.

Security Configuration

The configuration for user authentication and management are stored in the following file in the {MATONTO_HOME}/etc directory:

Table 2. MatOnto Security Configuration Files
Configuration File Description

org.matonto.jaas.engines.RdfEngine.cfg

Configurations for the MatOnto RDF Engine

MatOnto utilizes JAAS for user authentication and authorization. By default, user credentials and information are managed by the RdfEngine service which is configured with the org.matonto.jaas.engines.RdfEngine.cfg file. The file contains an id of the triple store to be used for storage, the encryption settings for JAAS which are enabled to start, and the two default roles: "user" and "admin". Apache Karaf will automatically detect any changes and reload the updated configurations.

The default user for MatOnto is "admin" with password "admin". To change the credentials of the "admin" user or perform any other user management activities, utilize the User Management page, the My Account page, or the appropriate REST endpoints.

Apache Karaf

The Karaf instance that runs MatOnto can be configured using the configuration files located in the {MATONTO_HOME}/etc directory.

Table 3. Relevant Karaf Configuration Files
Configuration File Description

org.ops4j.pax.url.mvn.cfg

Configurations for Maven repositories used for bundle resolution and deployment

org.ops4j.pax.web.cfg

Configurations for HTTPS connections

The org.ops4j.pax.url.mvn.cfg file specifies how Apache Karaf will resolve Maven URLs. This file is set up so that Apache Karaf will use the basic Maven repositories along with your local Maven repository and the public MatOnto remote repository to resolve artifacts.

The org.ops4j.pax.web.cfg file configures the web service Apache Karaf uses to run MatOnto. By default, MatOnto only runs HTTPS on port 8443.

Developer Guide

Prerequisites

To build the MatOnto source code, you must have the following software and tools installed.

Technology Version Download Link

Java

8

http://www.oracle.com/technetwork/java/javase/downloads/index.html

Maven

3.*

https://maven.apache.org/download.cgi

Node.js

4.*

https://nodejs.org/en/download/

Build from Source

Clone the MatOnto project from GitHub and navigate to that directory on your machine. Run the following command to build the source:

mvn clean install

The build creates the MatOnto distribution as both a .tar.gz file and a .zip file in the org.matonto.distribution/target directory. Extract one of the files and navigate into that directory.

Inside the extracted distribution directory, start up the MatOnto Karaf instance. For Unix/Linux:

bin/start

or for Windows:

bin\start.bat

All the MatOnto bundles and services and their dependencies will be automatically deployed using OBR.

The MatOnto web application should now be accessible at https://localhost:8443/matonto/index.html.

Appendix A: MatOnto Mappings

MatOnto mappings are used to convert delimited data into RDF and are made up of instances of classes defined in a custom ontology which can be found in the org.matonto.etl.api/src/main/resources/ directory in the delimited.ttl file. These main classes are:

Note

All examples in this Appendix will be in Turtle RDF serialization and use the following prefixes:

Prefix Namespace

example

http://guide.org/

delim

http://matonto.org/ontologies/delimited#

Mapping

The Mapping (http://matonto.org/ontologies/delimited#Mapping) class represents the mapping itself. Every mapping must have one and only one instance of the Mapping class. Properties associated with this class provide information about the mapping that are needed for the Mapping Tool to have context. There is only one property associated with this class, the sourceOntology property.

sourceOntology

The sourceOntology (http://matonto.org/ontologies/delimited#sourceOntology) property specifies the ontology a mapping is based on. The Mapping Tool requires this property in order to validate the class and property mappings within a mapping. It must point to an ontology that has been uploaded to MatOnto. A mapping will have access to all entities defined in ontologies within the imports closure of the source ontology.

Example 1. sourceOntology
example:DocumentExample delim:sourceOntology <http://matonto.org/ontologies/uhtc> .

ClassMapping

The ClassMapping (http://matonto.org/ontologies/delimited#ClassMapping) class represents a blueprint for creating an instance of a class. Every ClassMapping defined in a mapping will create an instance of the class it maps to for every row in a set of delimited data. Each class instance created will have a generated IRI. Properties associated with this class specify how the class instance it creates should be constructed. These properties are:

mapsTo

The mapsTo (http://matonto.org/ontologies/delimited#mapsTo) property specifies the class a ClassMapping will create. This is a required property for a ClassMapping since otherwise, the Mapping Tool will not know which class to create an instance of. It must point to a class that is defined either within the source ontology of the mapping or one of the ontologies in the source ontology’s imports closure.

Example 2. mapsTo
example:ClassMappingExample delim:mapsTo <http://matonto.org/ontologies/uhtc> .

dataProperty

The dataProperty (http://matonto.org/ontologies/delimited#dataProperty) property specifies a DataMapping that is associated with a ClassMapping. It must point to a DataMapping instance defined within the mapping. A ClassMapping can have one or more of this property. Every instance of a class created from a ClassMapping will have the property specified in the DataMapping specified by dataProperty.

Example 3. dataProperty
example:ClassMappingExample delim:dataProperty example:DataMapping1 ;
    delim:dataProperty example:DataMapping2 .

objectProperty

The objectProperty (http://matonto.org/ontologies/delimited#objectProperty) property specifies an ObjectMapping that is associated with a ClassMapping. It must point to a ObjectMapping instance defined within the mapping. A ClassMapping can have one or more of this property. Every instance of a class created from a ClassMapping will have the property specified in the ObjectMapping specified by objectProperty.

Example 4. objectProperty
example:ClassMappingExample delim:objectProperty example:ObjectMapping1 ;
    delim:objectProperty example:ObjectMapping2 .

hasPrefix

The hasPrefix (http://matonto.org/ontologies/delimited#hasPrefix) property specifies the namespace of the IRI for every class instance created by a ClassMapping. This property is required by the Mapping Tool so it knows how to construct the IRI for each class instance created by the ClassMapping. The value of this property is a string and must be a valid namespace.

Example 5. hasPrefix
example:ClassMappingExample delim:hasPrefix "http://guide.org/example/" .

localName

The localName (http://matonto.org/ontologies/delimited#localName) property specifies how the local name of the IRI will be generated for every class instance created by a ClassMapping. This property points to a string literal and must be in the following format. The string must start with a dollar sign ($) and contain either the string "UUID" or a number surrounded by curly braces "{}". The "UUID" string will generate a unique identifier for every class instance created by the ClassMapping. A number will grab the value of the column at that zero-based index in the row being mapped. If the column specified has duplicate values, the Mapping Tool will combine the properties of every class instance with that IRI and combine them into a single instance. If this property is not set on a ClassMapping, the Mapping Tool will default to generating a UUID for every class instance.

Example 6. localName

This means every class instance will have a unique identifier for a local name.

example:ClassMappingExample1 delim:localName "${UUID}" .

This means every class instance will have the value from the third column for a local name.

example:ClassMappingExample2 delim:localName "${2}" .

DataMapping

The DataMapping (http://matonto.org/ontologies/delimited#DataMapping) class represents a blueprint for creating a data property on a class instance. Since data properties in an ontology point to literal values, a DataMapping specifies a column whose value in the row being mapped will be used as the value of the generated data property. Properties associated with this class define how a data property will be created. These properties are:

columnIndex

The columnIndex (http://matonto.org/ontologies/delimited#columnIndex) property specifies which column a DataMapping should pull the value from to set as the value of the generated data property. This property is required for a DataMapping so that the Mapping Tool knows where to get the value of a data property. All column values retrieved by this property are interpreted as strings. The value of this property must be a string and all the column indexes are zero-based.

Example 7. columnIndex

This will retrieve the value from the first column.

example:DataMapping1 delim:columnIndex "0" .

hasProperty

The hasProperty (http://matonto.org/ontologies/delimited#hasProperty) property specifies which data property a DataMapping will create. This property is required for a DataMapping so that the Mapping Tool knows what property to create. It must point to a data property defined either within the source ontology of the mapping or one of the ontologies in the source ontology’s imports closure. This property can be associated with either a DataMapping or a ObjectMapping.

Example 8. hasProperty for DataMapping
example:DataMapping1 delim:hasProperty <http://matonto.org/ontologies/uhtc/aDataProperty> .

ObjectMapping

The ObjectMapping (http://matonto.org/ontologies/delimited#ObjectMapping) class represents a blueprint for creating an object property on a class instance. Since object properties in an ontology point to other classes or class expressions, an ObjectMapping specifies a ClassMapping that will be created for the same row and whose generated class instance will be used as the value of the generated object property. Properties associated with this class define how an object property will be created. These properties are:

classMapping

The classMapping (http://matonto.org/ontologies/delimited#classMapping) property specifies which class instance generated from a ClassMapping will be used as the value of the generated object property. This property is required for an ObjectMapping so that the Mapping Tool knows which class should be the value of the object property. The generated value will be the class instance created by the specified ClassMapping for the row being mapped. The value must be a ClassMapping defined within the mapping.

Example 9. classMapping
example:ObjectMapping1 delim:classMapping delim:ClassMappingExample .

hasProperty

The hasProperty (http://matonto.org/ontologies/delimited#hasProperty) property specifies which object property an ObjectMapping will create. This property is required for an ObjectMapping so that the Mapping Tool knows what property to create. It must point to a object property defined either within the source ontology of the mapping or one of the ontologies in the source ontology’s imports closure. This property can be associated with either a ObjectMapping or a DataMapping.

Example 10. hasProperty for ObjectMapping
example:ObjectMapping1 delim:hasProperty <http://matonto.org/ontologies/uhtc/aObjectProperty> .