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.

Note
You can check the status of the running server using the ./bin/status script or access the MatOnto shell using the ./bin/client script (that’s bin\status.bat and bin\client.bat for you Windows users).

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.

Note
The community distribution of ontologies in MatOnto is coming soon!

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 Simple Knowledge Organization System (SKOS) vocabulary editor. The ontology editor features tools for creating full OWL 2 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. The IRI can be copied quickly by clicking on it.

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. To add a new imported ontology, click on Add Import and enter the IRI of an ontology available on the web in the overlay.

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 all classes and their associated properties, including imports. 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. If an entity has been changed and those changes have not been committed, it will appear bold and an indicator will be shown on the right of the entity name. Imported classes and properties will appear grey and italicized. Clicking on an item in the tree will load that entity’s information into the other blocks in this section.

The title of the selected class or property, its IRI, and its type(s) are displayed at the top of the middle section. The IRI can be copied quickly by clicking on it. The middle blocks in this section allow you to add, remove, and edit Annotations and Axioms for the selected class or property. Imported classes and properties cannot be edited.

If you selected a property, a block with checkboxes for adding different characteristics to the selected property is shown in the top right of the Overview Section.

Note
See the W3C Specification for the definitions of property characteristics.

The last block on the right 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. If the number of usages exceeds 100, a button to load the next 100 is shown at the bottom of the block.

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, including imports, 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. If a class has been changed and those changes have not been committed, it will appear bold and an indicator will be shown on the right of the class name. Imported classes will appear grey and italicized. Clicking on an item in the hierarchy will load that class’s information into the other blocks in this section. Double clicking on a class with children will toggle the display of the children.

The title of the selected class, its IRI, and its type(s) are displayed at the top of the middle section. The IRI can be copied quickly by clicking on it. The middle blocks in this section allow you to add, remove, and edit Annotations and Axioms for the selected class. Imported classes cannot be edited.

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. If the number of usages exceeds 100, a button to load the next 100 is shown at the bottom of the block.

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 data, object, and annotation properties, including imports. The data, object, and annotation properties are grouped into three 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. If a property has been changed and those changes have not been committed, it will appear bold and an indicator will be shown on the right of the property name. Imported properties will appear grey and italicized. Clicking on an item in the hierarchy will load that property’s information into the other blocks in this section. Double clicking on a property with children will toggle the display of the children.

The title of the selected property, its IRI, and its type(s) are displayed at the top of the middle section. The IRI can be copied quickly by clicking on it. The middle blocks in this section change depending on whether you have selected a data, object, or annotation property. If the selected property is a data or object property, the blocks for adding, removing, and editing Annotations and Axioms are shown. If the selected property is an annotation property, only the Annotation block is shown. Imported properties cannot be edited.

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. If the IRI in this display already exists within the ontology, you will not be able to create the property. The Name field will populate the dcterms:title annotation. The Description field will populate the dcterms:description annotation. The Type radio buttons allow you to select whether you are creating a data, object, or annotation property. If you are creating a data or object property, more customization fields are available. The Characteristics checkboxes allow you to add different characteristics to the new property. 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 data property. You can optionally add language tags to the dcterms:title and dcterms:description properties using the field inside Show Language. You can also add rdfs:subPropertyOf relationships to other properties directly from this overlay by expanding Show Sub Property Of.

create property overlay
Figure 9. Create property overlay

If the selected property is a data or object property, a block with checkboxes for adding different characteristics to the selected property is shown in the top right of the Properties Section. Imported properties cannot be edited.

Note
See the W3C Specification for the definitions of property characteristics.

The last block on the right of the 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. If the number of usages exceeds 100, a button to load the next 100 is shown at the bottom of the block.

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, including imports, nested under their classes based on the rdfs:subClassOf property. If an individual has been changed and those changes have not been committed, it will appear bold and an indicator will be shown on the right of the individual name. Imported individuals will appear grey and italicized. Clicking on an item in the list will load that individual’s information into the other blocks in this section.

The title of the selected individual, its IRI, and its type(s) are displayed at the top of the middle section. The IRI can be copied quickly by clicking on it. The blocks 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. Imported individuals cannot be edited.

Search Section

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

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 blocks in this section. Double clicking on an entity will open that entity in the appropriate tab.

The right block 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, 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, including imports. The top level items are the concept schemes, or subclasses of skos:ConceptScheme, and their children are all concepts, or subclasses of skos:Concept, 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. If a concept scheme or concept has been changed and those changes have not been committed, it will appear bold and an indicator will be shown on the right of its name. Imported concept schemes and concepts will appear grey and italicized. Clicking on an item in the hierarchy will load that concept scheme’s or concept’s information in the other blocks in this section. Double clicking on a concept scheme or concept with children will toggle the display of the children.

The title of the selected concept scheme or concept, its IRI, and its type(s) are displayed at the top of the middle section. The IRI can be copied quickly by clicking on it. The middle blocks in this section allow you to add, remove, and edit Annotations and Relationships for the selected property. Imported concept schemes and concepts cannot be edited.

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. If the number of usages exceeds 100, a button to load the next 100 is shown at the bottom of the block.

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

Every edit made to an entity within an ontology or vocabulary is automatically saved and an indicator is shown in the top right if the most recent changes have been saved successfully. The 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 changes
Figure 15. Ontology Editor Changes Section

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

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 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 and graph 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. The graph displays each commit connected to its parent commits continuing backwards until the initial commit. To view more information about a particular commit in the history, such as the added and deleted statements, click on its id or associated circle in the graph.

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. You cannot create/save an edited IRI that already exists within the ontology. 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 data 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 or Manchester Syntax if it is supported. 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 you have made changes to an ontology or vocabulary, the Commit Changes button will become active. Clicking on this button will bring up the Add Commit overlay.

commit changes button
Figure 24. Commit button

The Add Commit overlay provides a textarea for you to enter in a Comment 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 25. Add commit overlay
add commit overlay message
Figure 26. Add commit overlay with message

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 27. 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 28. 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.

full mapping tool initial view
Figure 29. 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.

The initial view of the Mapping Tool shows the Mapping Select Page. The left side displays a searchable list of all the mappings within the local MatOnto repository along with buttons to create and delete mappings. Clicking on a mapping in this list loads its information into the right side of the page. The preview of the mapping includes the classes and properties it maps and the title of the source ontology along with buttons for editing, running, and downloading the mapping. If the selected source ontology no longer exists in the local MatOnto repository, you will not be able to edit or run the mapping.

Creating a Mapping

To create a new mapping, click Create Mapping on the Mapping Select Page. The creation overlay requires you to enter a valid unique name for the mapping. The radio buttons allow you to select whether the new mapping should be made from scratch or generated using a saved mapping as a template.

create mapping overlay
Figure 30. Create Mapping Overlay

Clicking Continue brings you to the File Upload Page to continue the process of creating a mapping. You must upload a delimited file to use as a standard for the mapping. You can also 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. Selecting a file in the form on the left loads a preview of the first 50 rows and columns of the delimited file into the table on the right. From this page, you can also edit the name of the mapping using the pencil button next to the name. If you had selected to create the mapping from a saved mapping and the delimited file you choose does not contain enough columns for the mapping’s data property mappings, a list of the missing columns are displayed under the file select. However, you can still edit the mapping as long as those data properties are fixed. Clicking Continue or Fix brings you to the Edit Mapping Page.

file upload create
Figure 31. File Upload Page for Creating a Mapping
file upload create missing columns
Figure 32. File Upload Page for Creating a Mapping with missing columns

The Edit Mapping Page contains two tabs, Edit and Preview. The Edit tab contains a section for displaying the currently selected source ontology, the list of class mappings, and a list of property mappings for a particular class. For every row in the delimited data, an instance of a mapped class will be made according to each class mapping. Each created class instance will have a set of properties as defined by the property mappings associated with each class mapping. The values of data properties will have assigned datatypes based on the range of the mapped data property. The Preview tab allows you to map the first 10 rows of the selected delimited file using the current state of the mapping in a variety of different RDF serializations. From this page, you can also edit the name of the mapping using the pencil button next to the name.

Note
To learn about the structure of a mapping, refer to the MatOnto Mappings Appendix.
edit mapping edit
Figure 33. Edit Mapping Page Edit Tab

When creating a mapping, the first thing you will see is the Source Ontology Overlay. This setting can always be changed by clicking the pencil button next to the ontology name in the Edit form. The Class section contains a select box contains all the class mappings, a button to delete a specific class mapping, and a button to create a new class mapping. Currently there can only be one class mapping per class. Clicking Add Class opens an overlay where you can select a class in the imports closure of the source ontology that has not already been used for a class mapping.

The IRI Template section displays the template MatOnto will use when creating IRIs for the created class instances from the selected 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 with all white space removed as the local name for the class instance. This template can be edited by clicking the pencil button next to the section title and filling in the fields in the IRI Template Overlay.

The Properties section lists all the property mappings for the selected class mapping with a button to add a new property mapping. Object property mappings are displayed with the name of the class mapping whose instances will be used as the range of the property. Data property mappings are displayed with the name of the column whose values will be used as the range of the property along with a preview of what the first value would be. Each property mapping also provides a button to edit and delete. If a data property mapping is invalid, meaning it points to a column that does not exist in the delimited file, it must be handled before the mapping can be saved or run.

Clicking Add Property opens an overlay where you can select a property in the imports closure of the source ontology or a common annotation that has not already been mapped. Annotations that can be mapped are rdfs:label, rdfs:comment, dcterms:title, and dcterms:description. If you select a data property or an annotation, a select box appears containing identifiers for each column in the delimited file along with a preview of the first value of the selected column. If you select a object property, the created property mapping will link to a class mapping of the appropriate type in the mapping. A new class mapping for the range type will be created if one does not already exist.

create property mapping overlay data
Figure 34. Create Property Mapping Overlay for a Data Property
create property mapping overlay object
Figure 35. Create Property Mapping Overlay for an Object Property

Clicking Save at the bottom of either the Edit or Preview tab saves the current state of the mapping and brings you back to the Mapping Select Page. Clicking Save & Run opens an overlay where you can choose whether to download the mapped data or upload it into a dataset within a MatOnto repository. Clicking Run in that overlay will save the current state of the mapping and run it.

Note
To learn about datasets in MatOnto, refer to the Datasets Manager.

Editing a Mapping

To edit a mapping, click Edit on the Mapping Select Page. The application performs 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 is displayed informing you of the error. If it passes, you are brought to the File Upload Page where you must upload a delimited file to use as a standard for the mapping. From here, editing the mapping works the same as creating a mapping including how missing columns are handled.

file upload edit
Figure 36. File Upload Page for Editing a Mapping
file upload edit missing columns
Figure 37. File Upload Page for Editing a Mapping with missing columns

Running a Mapping

To run a mapping against delimited data without editing it, click Run on the Mapping Select Page. The application performs 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 is displayed informing you of the error. If it passes, you are brought to the File Upload Page where you must upload a delimited file to be used when generating RDF data. You can also 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. The classes and properties that will be created using the mapping are displayed under the file select. The columns that must be present in the delimited file are highlighted in the table on the right. Selecting a file in the form on the left loads a preview of the first 50 rows and columns of the delimited file into the table. If the delimited file is missing a column, the property that requires it turns red and you will not be able to run the mapping. Clicking Run opens an overlay where you can choose whether to download the mapped data or upload it into a dataset within a MatOnto repository.

Note
To learn about datasets in MatOnto, refer to the Datasets Manager.
file upload run
Figure 38. File Upload Page for Running a Mapping
file upload run missing columns
Figure 39. File Upload Page for Running a Mapping with missing columns

Mapping Tool Reference

Source Ontology Overlay

The Source Ontology Overlay allows you to select the source ontology for the mapping from all uploaded ontologies in the local MatOnto repository.

source ontology overlay
Figure 40. Source Ontology Overlay

The left side of the overlay contains a searchable paginated list of all the ontologies in the local MatOnto repository and a select for the version of the ontology to use. For most ontologies, this will only contain the "Latest" value. However, if an ontology was previously selected for a mapping and that ontology has changed since then, there will be an option for the "Saved" version of the ontology. The right side of the overlay displays information about the ontology from its record in the Catalog and a collapsible list of the classes in that ontology. Setting the source ontology will remove any class and property mappings in the mapping that are incompatible. Class mappings and property mappings are incompatible if the class or property that is referenced no longer exists in the imports closure of the source ontology. Property mappings are also incompatible if they are a different type or have a different range.

IRI Template Overlay

The IRI Template overlay provides you a way to edit each portion of the IRI template of a class mapping. The template will be used to generate the IRIs for each instance created by a class mapping.

iri template overlay

The Begins with field (required) is the beginning of the IRI. This is more commonly known as the namespace. 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 dropdown field (required) is the last part of the IRI. This value is commonly known as the local name. The values in this dropdown are "UUID", which represents generating a unique identifier as the local name for each generated instance of each row, and the title of each column, which represents using the value of that column as the local name for each generated instance of each row. Clicking Cancel will close the overlay. Clicking Edit will save the IRI template.

Datasets Manager

The MatOnto Datasets Manager allows users to create, clear, and delete datasets within the application to group and store Resource Description Framework (RDF) semantic data into various graphs for enhanced query isolation, data segmentation, and management.

Note
To learn more about the structure of a dataset, refer to the MatOnto Datasets Appendix.

To reach the Datasets Manager, click on the link in the left menu.

full datasets manager initial view
Figure 41. The Datasets Manager

The page displays a paginated list of all the datasets within the local MatOnto repository. Each dataset in the list displays a preview of the dataset metadata, a clear button, and a delete button. Clicking on a dataset displays the rest of the dataset metadata. Deleting a dataset deletes the dataset, catalog record, and all associated data graphs. Clearing a dataset removes all associated data graphs except the system default named graph. Clearing a dataset does not remove the dataset or the catalog record. This list can also be filtered with search text.

To create a new dataset, click New Dataset and fill out the information in both steps of the creation overlay.

new dataset overlay 1
Figure 42. New Dataset Overlay Step One

The first step of creating a dataset involves the following. The Title field populates the dcterms:title annotation of the new dataset record. The Dataset IRI field allows you to specify what the IRI of the new dataset should be. If not provided, the system will create a unique one for you. The Description field populates the dcterms:description annotation of the new dataset record. The Keywords field will attach the entered values as keywords to the new dataset record. The Repository ID field displays the identifier of the repository registered within MatOnto where the dataset and all associated named graphs will be stored. For now, this is defaulted to the system repository. Clicking Cancel will close the overlay. Clicking Next will bring you to the second step of the process.

Note
The ability to create new repositories in MatOnto is coming soon!
new dataset overlay 2
Figure 43. New Dataset Overlay Step Two

The second step of creating a dataset is to select which ontologies should be used as the basis for the data. Select an ontology from the searchable paginated list of ontologies to add it to the dataset. To remove a selected ontology, click the red x next to the ontology name. Clicking Back will take you back to the first step of the creation process. Clicking Submit will create the dataset with the provided metadata.

Discover

The MatOnto web-based Discover page allows users to search their data at various levels of depth. The Explore tab provides an intuitive interface for quickly navigating through defined instances. The Query tab allows users to formulate and execute SPARQL 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.
Note
The ability to save and reuse SPARQL queries is coming soon!

To reach the Discover page, click on the link in the left menu. The first tab shown is the Explore tab.

full discover page initial view
Figure 44. The Discover Page

Explore

The Explore tab of the Discover page allows you to get a high-level overview of the structure of your data within a dataset.

explore classes
Figure 45. Explore tab with classes

The Explore tab opens with a view of all the classes found within the selected dataset. Each card displays the label and a brief description about a class, the number of instances defined as that class, a few of those instances, and a button to explore the instances themselves. Clicking Explore Data opens the instances view.

explore instances
Figure 46. Explore Tab with instances

The instances view contains a paginated list of all the instances defined as a particular class. Each card displays the label and brief description about an instance. The label is determined based on the values of the rdfs:label, dc:title, or dcterms:title properties on the instance. The description is based on the values of the rdfs:comment, dc:description, or dcterms:description properties on the instance. You can navigate back to the classes view using the breadcrumb trail in the top left.

Query

The Query tab of the Discover page allows you to submit SPARQL query against the MatOnto repository and optionally a specific dataset.

query full view
Figure 47. Query tab

There are two main blocks of the Query tab. The top block contains an editor to enter a SPARQL query, several configuration fields, 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 are not used in the results display. The Dataset field contains a list of all available datasets within the MatOnto repository. Selecting a dataset limits the query to search through the data within the selected dataset. Clicking Submit executes the entered query against the MatOnto repository, optionally limited by the selected dataset, and updates the bottom block with the results.

The bottom block contains the paginated results of your last SPARQL query against the MatOnto repository in a table format. The headers of the table are the variables specified in the SPARQL query. Each row of the table represents a single RDF triple. To download the results of the latest query in a tabular file, click on the download button in the lower right and fill out the form in the overlay.

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.

Note
Federation of catalogs in MatOnto is coming soon!

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

full catalog initial view
Figure 48. The Catalog

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!

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 and a header section with a breadcrumb trail of the entities you have opened 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 49. Catalog Record 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 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. The rest of the main body contains the list of matching Records. 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.

catalog page
Figure 50. Catalog Page

Record Page

The Record Page displays all metadata for the associated Record along with a paginated list of any sub-entities. The main body of the Record Page contains all the metadata about the associated Record and a sortable paginated list of any sub-entities of the Record. This list will differ depending on the type of the associated Record and may not be shown at all. For example, if the Record is a Versioned RDF Record, the list of Branches for that Record will be shown. Clicking on a Branch entry will bring you to the associated Branch Page.

record page versionedrdfrecord
Figure 51. Record Page

Branch Page

The Branch Page displays all metadata for the associated Branch. The main body of the Branch Page contains all the metadata about the associated Branch and a table with a graph of the commit history of the Branch. The username of the creator, ID, message, and date for each commit are displayed within the table. The graph displays each commit connected to its parent commits continuing backwards until the initial commit. To view more information about a particular commit in the history, such as the added and deleted statements, click on its id or associated circle in the graph.

branch page
Figure 52. Branch Page

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 53. My Account link

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

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 section
Figure 54. Profile Section

Groups

The Groups section contains a list of all the groups you belong to. Next to each group title is an indicator of how many users are within that group. If a group has the admin role, an indicator will be next to the group’s title.

groups section
Figure 55. Groups Section

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 section
Figure 56. Password Section

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. This option is not available to non-administrators.

user management link
Figure 57. User Management link

There are two main sections of the User Management page:

Users

The Users section allows you to create, edit, and remove users from the application.

users section
Figure 58. Users Section

The left side of the section contains a list of all the users in MatOnto. Each user is displayed using their first and last names, if available, or their username. If a user is an administrator, whether by 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 first name, last name, or username. Clicking on a user will load that user’s information into the right side of the section.

The middle of the Users section contains the username of the selected user, a block for viewing and editing the user’s profile information, and a block for resetting the user’s password. Resetting a user’s password cannot be undone.

The right side of the section contains blocks for viewing and editing the selected user’s permissions and viewing the user’s groups. Clicking on the title of a group will open it in the Groups section.

To create a user, click Create User and fill out the fields in both steps of the Create User Overlay.

create user overlay 1
Figure 59. Create User Overlay Step One

The first step 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 step of the process.

create user overlay 2
Figure 60. Create User Overlay Step Two

The second step of creating a user 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 step of the process. Clicking Add will create a new user with the entered information in both overlays.

Groups

The Groups section 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.

groups section
Figure 61. Groups Section

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.

The right side of the section contains the selected group’s title and two rows of blocks. The top row contains blocks that allow you to edit the group’s description and permissions. If a group has the "Admin" role, all members within that group are considered administrators.

The bottom row contains a block that allows you to view, add, and remove 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. Clicking on a username in this table will open that user’s information in the Users section.

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 62. Create group overlay

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 found in the org.matonto.etl.api/src/main/resources/delimited.ttl file in the source code. 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 delim: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. These properties are:

sourceRecord

The delim:sourceRecord property specifies the OntologyRecord a mapping uses for its classes and properties. The Mapping Tool requires this property along with sourceBranch and sourceCommit to retrieve a specific version of an ontology saved in MatOnto. A mapping will have access to all entities defined in ontologies within the imports closure of the source ontology. The Mapping Tool utilizes all class and property definitions to validate the class and property mappings and apply the correct datatypes to data property values.

Example 1. sourceRecord
example:DocumentExample delim:sourceRecord <http://matonto.org/records/uhtc> .

sourceBranch

The delim:sourceBranch property specifies the Branch of the sourceRecord a mapping uses for its classes and properties. The Mapping Tool requires this property along with sourceRecord and sourceCommit to retrieve a specific version of an ontology saved in MatOnto. A mapping will have access to all entities defined in ontologies within the imports closure of the source ontology. The Mapping Tool utilizes all class and property definitions to validate the class and property mappings and apply the correct datatypes to data property values.

Example 2. sourceBranch
example:DocumentExample delim:sourceBranch <http://matonto.org/branches/master> .

sourceCommit

The delim:sourceCommit property specifies the Commit of the sourceBranch a mapping uses for its classes and properties. The Mapping Tool requires this property along with sourceRecord and sourceBranch to retrieve a specific version of an ontology saved in MatOnto. A mapping will have access to all entities defined in ontologies within the imports closure of the source ontology. The Mapping Tool utilizes all class and property definitions to validate the class and property mappings and apply the correct datatypes to data property values.

Example 3. sourceCommit
example:DocumentExample delim:sourceCommit <http://matonto.org/commits/0> .

ClassMapping

The delim: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 delim: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 4. mapsTo
example:ClassMappingExample delim:mapsTo <http://matonto.org/ontologies/uhtc> .

dataProperty

The delim: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 5. dataProperty
example:ClassMappingExample delim:dataProperty example:DataMapping1 ;
    delim:dataProperty example:DataMapping2 .

objectProperty

The delim: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 6. objectProperty
example:ClassMappingExample delim:objectProperty example:ObjectMapping1 ;
    delim:objectProperty example:ObjectMapping2 .

hasPrefix

The delim: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 7. hasPrefix
example:ClassMappingExample delim:hasPrefix "http://guide.org/example/" .

localName

The delim: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 8. 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 delim: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 delim: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 9. columnIndex

This will retrieve the value from the first column.

example:DataMapping1 delim:columnIndex "0" .

hasProperty

The delim: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 10. hasProperty for DataMapping
example:DataMapping1 delim:hasProperty <http://matonto.org/ontologies/uhtc/aDataProperty> .

ObjectMapping

The delim: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 delim: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 11. classMapping
example:ObjectMapping1 delim:classMapping delim:ClassMappingExample .

hasProperty

The delim: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 12. hasProperty for ObjectMapping
example:ObjectMapping1 delim:hasProperty <http://matonto.org/ontologies/uhtc/aObjectProperty> .

Appendix B: MatOnto Datasets

MatOnto datasets are used to group and store RDF data into various graphs for enhanced query isolation, data segmentation, and management. The MatOnto dataset structure is defined in a custom ontology found in the org.matonto.dataset.api/src/main/resources/dataset.ttl file in the source code. This design is loosely based on the W3C Specification for SPARQL Datasets wherein a collection of graphs can be queried as default named graphs or named graphs. The primary class is dataset:Dataset, and the properties associated with this class provide information about all the named graphs within the dataset. These properties are:

Note

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

Prefix Namespace

example

http://guide.org/

dataset

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

systemDefaultNamedGraph

The dataset:systemDefaultNamedGraph property specifies the default named graph that MatOnto will use when loading data that does not specify a graph (e.g. data from a Turtle file). For example, this approach is currently used for data created by the Mapping Tool. This named graph will be cleared, but not removed when a dataset is cleared.

Example 13. systemDefaultNamedGraph
GRAPH example:DatasetExample {
    example:DatasetExample a dataset:Dataset ;
        dataset:systemDefaultNamedGraph example:sdng .
}

GRAPH example:sdng {
    example:Subject a example:Object .
}

defaultNamedGraph

The dataset:defaultNamedGraph property specifies a default named graph within the dataset. These graphs are not maintained by the system and can be used when data segmentation is required within a dataset. These graphs are removed when a dataset is cleared.

Example 14. defaultNamedGraph
GRAPH example:DatasetExample {
    example:DatasetExample a dataset:Dataset ;
        dataset:defaultNamedGraph example:dng .
}

GRAPH example:dng {
    example:Subject a example:Object .
}

namedGraph

The dataset:namedGraph property specifies a named graph within the dataset. These graphs are not maintained by the system and can be used when data segmentation is required within a dataset. These graphs are removed when a dataset is cleared.

Example 15. namedGraph
GRAPH example:DatasetExample {
    example:DatasetExample a dataset:Dataset ;
        dataset:namedGraph example:ng .
}

GRAPH example:ng {
    example:Subject a example:Object .
}

Appendix C: Release Notes

Release Notes for MatOnto 1.7

MatOnto 1.7 released on June 5, 2017. This release includes many bug fixes and performance improvements for the ontology editor and mapping tool as well as a new Discover Module for exploring datasets.

General Improvements and Fixes

  • Fixed an issue where retrieving users with email addresses in the User Management tool caused an Internal Server Error

Discover Module

  • Replaced the existing SPARQL Editor Module with the new Discover Module

  • Added "Explore" tool to the Discover Module to enable quick exploration of datasets. This new tool will show the user what types of data are stored in the dataset and provide data samples. Future updates to the tool will allow users to explore and modify instance properties, create new instances, and delete existing instances.

  • Fixed an issue where comments were not allowed in SPARQL queries against datasets

Ontology Editor

  • Improved parsing of entity local names with acronyms used for display values (e.g. http://example.com/ontology#ABCEntity → "ABC Entity")

  • Support added for directly adding a subClassOf or subPropertyOf axiom when creating a new class or property

  • Fixed an issue allowing users to create multiple ontology entities with the same IRI

  • Fixed an issue where some commit data was not removed when deleting an ontology

  • Fixed an issue where the individuals tree was not updated correctly when the ontology class tree changed

  • Fixed an issue where a user could not assign a ConceptScheme when creating a new Concept

Mapping Tool

  • Support added for applying datatypes to literals based on the selected ontology properties

  • Support added for using basic rdfs and dcterms properties in a mapping

  • Support added for mapping multiple properties to the same source data column

  • Fixed an issue where modifying an ontology that was also being used in an active mapping broke the mapping ontology selector

  • Fixed an issue where the Mapping Tool was not properly including ontology updates when selecting the latest ontology version

API Updates

  • Refactored public Catalog API to include path validation when performing operations such as creating commits and merging branches

  • Significant performance improvements when retrieving commit data from the Catalog REST endpoints. Dramatically reduces load times for large ontologies.

  • Support added for creating commits from external data. This capability will enable future support for applying commits from files and merging records.

  • Various improvements to memory management when opening ontologies. Dramatically reduces memory usage when opening large ontologies.

Known Issues

  • In the Vocabulary Editor, SKOS relationship properties are missing from the property selector when using subclasses of skos:Concept. This issue will be fixed in Release 1.8.

  • Intermittent build errors occur in the Catalog REST bundle due to some shared resources. This issue will be fixed in Release 1.8.

  • The Mapping improperly includes InProgressCommit data when loading ontology properties and classes. This issue will be fixed in Release 1.8.

  • SPARQL queries against datasets that include SPARQL keywords as variable names cause a parsing exception. This issue will be fixed in a future release.

  • Classes that subclass each other should result in an equivalence relationship. This is not properly rendered in the Ontology Editor and produces errors. This issue will be fixed in a future release.

  • The Mapping Tool does not correctly handle mapping object properties with no range. The tool allows you to select the object property, but produces an error when trying to determine the target class type. This issue will be fixed in a future release.

  • The Mapping Tool does not correctly save mappings that have had their name changed. This issue will be fixed in Release 1.8.

Release Notes for MatOnto 1.6

MatOnto 1.6 released on May 8, 2017. This release includes many bug fixes and performance improvements for the ontology editor as well as various improvements to the mapping tool and user management page.

General Improvements and Fixes

  • Google groups link added to help menu

  • User management user list now displays full name if available

  • Access to user management page restricted to admins only

  • Support added to list a user’s groups in the profile page

  • Fixed an issue where targeted spinner would lock up the application in several places

  • Fixed an issue where admin tags were not displayed correctly in the user list of the user management page

Ontology Editor

  • Support added for a click-to-copy feature for ontology entity IRIs

  • Support added to render complex class expressions and restrictions using Manchester Syntax in Axioms panel

  • Support added to render complex class expressions and restrictions using Manchester Syntax in Search panel

  • Support added to include imported entities in class, property, and individual list

  • Support added to roll-up large number of entity usages into a link to increase performance

  • Support added to render individuals of subtypes of skos:Concept in the concept hierarchy of the vocabulary editor

  • Support added to implement virtual scrolling on all entity lists, dramatically improving performance for large ontologies

  • Support added to render indviduals as a tree based on their class hierarchy

  • Support added to implement ontology caching, dramatically improving performance when loading and editing large ontologies

  • Support added to immediately render icons associated with ranges of properties in the property hierarchy and overview tab

  • Fixed an issue where deleting an ontology did not delete the underlying revision data

  • Fixed an issue where creating and deleting classes sometimes resulted in incomplete class data remaining in the ontology

  • Fixed an issue where import statements were not correctly displayed in the changes tab

  • Fixed an issue where adding and deleting mulitple imports did not correctly delete the specified import

  • Fixed an issue where deleting individuals did not always remove them from the individuals list

  • Fixed an issue where axiom values were not displayed properly in dropdowns

  • Fixed an issue where the String datatype was being removed from an individual’s data property when committing

  • Fixed an issue where modification badges would not be removed after performing a commit

  • Fixed an issue where the project tab would not update on branch change

Mapping Tool

  • Support added for editing full IRI in IRI templates

  • Support added to ignore property mappings for empty cells when mapping in delimited and excel files

  • Support added to ignore class mappings for empty rows when mapping in delimited and excel files

  • Support added to trim white space from values inserted into IRI templates

  • Support added to show a preview of mapped data in the property mappings list

  • Fixed an issue where the edit and delete buttons for property mappings would not work in Firefox

  • Fixed an issue where the user could not create a new class mapping when editing a previously created mapping resource

  • Fixed an issue where previewing mapping results intermittently did not display correctly

  • Fixed an issue where using an ontology with the same class defined in the ontology and one of its imports resulted in an empty dropdown when adding a class mapping

  • Fixed an issue where page leave confirmation message was displayed when downloading a mapped data

Datasets

  • Support added to associate datasets with ontologies that describe the data within them

Release Notes for MatOnto 1.5

MatOnto 1.5 released on April 4, 2017. This release contains the first features for MatOnto datasets and many improvements to the Ontology Editor user experience.

Datasets

A new feature in 1.5, MatOnto Datasets provide collections of RDF graphs that can be managed and queried independently of other data stored within MatOnto repositories.

  • Datasets consist of a collection of RDF graphs that act as default named graphs or named graphs per the SPARQL 1.1 recommendation for RDF Datasets.

  • Java and REST services are now available for creating, managing, and querying datasets. The services ensure all operations on the Dataset are isolated to that specific set of RDF graphs.

  • A new UI module provides capabilities for creating and managing datasets.

Ontology Editor

  • Support added for displaying and editing language tags on string literals.

  • Support added for displaying and selecting if a property is functional.

  • Support added for importing ontologies from a URL. When adding an import, the editor will confirm the URL is resolvable and reload the ontology with the imported entities.

  • The Commits tab now renders a commit history chain with links to view the commit changes.

  • Added support for loading spinners over specific UI components when waiting on asynchronous calls to load data. This can be seen in the entity usages block.

  • All entity hierarchy trees are now sorted alphabetically.

  • When rendering labels for entities in hierarchy trees or detail blocks, a "pretty-print" label is displayed using the rdfs:label, dc:title, or the local name of the IRI in that order.

  • The editor now supports passive saving. When an ontology entity is modified, the ontology is automatically saved.

  • Modified entities are now highlighted using a modification badge and bold formatting.

  • Support added for creating custom Annotation Properties.

  • Each entity now displays a list of its rdf:type.

Mapping Tool

  • Integration with MatOnto Datasets provides the capability to upload transformed data to a Dataset.

  • Removed the idea of a "Base Class" from the mapping configuration. You now select from a list of classes in an order to create class mappings.

SPARQL Query Editor

  • Integration with MatOnto Datasets provides the capability to limit a query operation to a particular Dataset.

  • Malformed queries now properly display a message describing the parsing error.

  • New feature allows user to download the results of a SPARQL tuple query in CSV, TSV, or Excel format.

General Improvements and Fixes

  • User management tool now allows an admin to reset a user’s password.

Known Issues

  • Double-clicking an entity in the Ontology Editor search results wil not remove the loading spinner. Reload the browser tab to clear this issue.