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.

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. 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. Selecting 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 middle blocks in this section allow you to add, remove, and edit Annotations and Axioms for the selected class or property.

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.

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. 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. 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 middle blocks 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 data, object, and annotation properties. 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. 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 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.

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

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.

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.

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

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 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. 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. 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. 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 middle blocks 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

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. 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 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 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 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 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 datatype 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 datatype 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 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 source ontology or its imports 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 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 overlay.

The Properties section lists all the property mappings for the selected class mapping with a button to add a new property mapping. Each listed property mapping displays a description of the value that will be generated. For object properties this is the name of the class mapping whose instances will be used. For data properties, this is the name of the column whose value in each row will be used. 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 source ontology or its imports that has not already been mapped. If you select a data property, a select box appears containing identifiers for each unused column in the delimited file. 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 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 map no longer exist in the source ontology or its imports. Property mappings are also incompatible if they are a different type or have a different range.

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 the creation overlay.

new dataset overlay
Figure 42. New Dataset Overlay

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.

Note
The ability to create new repositories in MatOnto is coming soon!

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.

full editor initial view
Figure 43. SPARQL Editor link

There are two main sections of the SPARQL Query Editor:

Query Editor

The Query Editor contains a text area 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 will not be used in the Query Results display. The Dataset field contains a list of all available datasets within the MatOnto repository. Selecting a dataset will limit the query to search through the data within the selected dataset.

query editor
Figure 44. Query Editor with a prefix and dataset selected

Clicking Submit will execute the entered query against the MatOnto repository, optionally limited by the selected dataset, and update the Query Results section with the results.

Query Results

The Query Results section will show the paginated 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. 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. 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.

query with three variables
Figure 45. Sample query with three variables
results with three variables
Figure 46. 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.

full catalog initial view
Figure 47. 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 48. 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 49. 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 50. 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 51. 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 52. My Account link

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

my account tabs
Figure 53. 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 54. Profile page
profile success
Figure 55. 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 56. Password page
password success
Figure 57. 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 58. 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 59. 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 60. 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 61. 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 62. Delete group overlay

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

group title
Figure 63. 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 64. 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 65. 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 66. 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 67. 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 68. 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 69. 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 70. Delete user overlay

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

username
Figure 71. 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 72. 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 73. 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 74. 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 75. 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 76. 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 77. 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 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. There is only one property associated with this class, the sourceOntology property.

sourceOntology

The delim: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 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 2. 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 3. 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 4. 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 5. 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 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 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 7. 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 8. 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 9. 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 10. 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 11. 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 12. 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 13. 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.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.