Working with Ontologies

Table of Contents

Ontology is a special kind of an asset collection in TopBraid EDG. Ontologies and ontology modeling are key to EDG since ontologies define schemas for all other types of collections. In EDG, ontologies are defined using SHACL, the World Wide Web Consortium’s (W3C) standard for defining graph data models. W3C is the same organization that is responsible for defining standards for XML, HTML, CSS and other web technologies. To learn more about SHACL, see https://www.w3.org/TR/shacl/ and TopQuadrant’s web page about SHACL https://www.topquadrant.com/technology/shacl/.

TopBraid EDG also supports RDFS and OWL which are the earlier generation of modeling languages defined by the W3C. You can load into EDG any standard ontology. Using features on the Transform tab for ontologies, you can then auto-generate SHACL model definitions from RDFS/OWL.

Ontologies contain classes (asset types) and associated properties – attributes and relationships. Classes in EDG are also node shapes. Node shapes define schema for class members – assets of a given type. Properties are declared for classes using property shapes. Within a property shape, you can define so-called constraints on property values e.g., number of values, their type and more. If you have learned object oriented modeling in the past, you will find these concepts familiar.

It is also possible to create node shapes that are not classes. These shapes define alternative views into an asset. For example, the Business Term class/node shape pre-built in the EDG provided ontologies defines a number of properties for business terms. You may want to have a more abridged view of a Business Term for certain stakeholders. To support this, you can define a node shape that is not a class, associate with it only a subset of properties and target it to members of the Business Term class.

In addition to property definitions that specify type of property values, number of values and other constraints, ontologies can also contain inference rules that calculate or derive new facts from existing facts.

Ontologies contain schema and rules. Instance data however, should be created in other collection types such as data graphs, taxonomies or reference datasets. Ontology Editor in EDG offers only limited features for working with instances in the cases of a small amount of enumerated values like, for example, days of the week.

This guide is focused on the features of the ontology editing application and the features of the Manage and Export tab that are unique for ontologies. Please see the Asset Collection Guide for all the general features available for asset collections such as import/export, editing, user permissions, reports and settings.

Customizing Ontologies Provided with EDG

Majority of TopBraid EDG’s asset collection are based on pre-specified ontologies shipped with TopBraid EDG.

These pre-specified ontologies are located in EDG workspace as files:

  • Taxonomies in EDG are based on SKOS or SKOS-XL.
  • Data assets, enterprise assets, technical assets, requirements, glossaries, enumerations, lineage models and the governance model are based “EDG ontologies”. Their names start with “EDG Shapes”, followed by the asset collection type. For example, “EDG Shapes – Data Assets”.
  • Corpora are based on a model called “TopBraid Simple Corpus and Document Schema”.

The exception to this rule are:

  • Reference datasets and data graphs – these are based on the user defined ontologies
  • Crosswalks and content tagsets – these asset collections contain only links between other collections
  • Ontologies themselves – as described here, they are primariiy based on SHACL

The process for customizing pre-built models is described below:

  • Create an ontology in EDG
  • Include in it an EDG provided model corresponding to the asset collection type you want to change
  • Make changes to your ontology:
    • You can freely add classes, node shapes, properties and property shapes
    • You should not delete properties or property shapes. In fact, since they are included by reference, you will not be able to do so. Instead, de-activate a shape for a property you need to remove by setting deactivated to true
    • You should not (and will not be able to) remove subclass relationship between pre-built classes. Instead, you can add new sub class relationships in the ontology and then change the Root Class for specific asset collections (using its Manage tab)
  • Include your customized ontology into an asset collection you want to have the modifications. If you changes should apply to all collection of a given type, EDG Administrators can define it as a default include for the type. This option is available under the EDG Configuration Parameters page.

If different groups in your organizations need to have different customizations, each should follow the process outlined above to address their specific customizations needs. EDG Getting Started with Business Glossaries guide provides an example of using this approach to customize a glossary.

If your organization decides that you need to physically remove anything in the pre-built ontologies, such changes can only be made directly to the underlying files. Should you decide to do this, the changes you make will need to be backed up and, possibly, reconciled with changes to the EDG models in the future releases.

 

Ontology Editor Overview

 

EDG collection editors are composed of panels. The example below is the default view for ontologies. Panels here are labeled 1-5. Just like the other collection editors, the UI for this editor can be customized and arranged and comes with many panels and layouts.

For information on the panels specific to the ontology editor, see Ontology Editor Panels. For information on the general aspects of using EDG editors and on other panels, please see Asset Collection Guide – Editor.

Classes vs. Instances

TopBraid EDG implements the recommend practice that instance data should be separated from their class definitions, which are included via one or more ontologies. Ontologies define classes, properties, and shapes (SHACL constraints) and other asset collection types (e.g., taxonomy, etc.) contain only instances.

If any non-ontology collection needs special classes (e.g., subclasses of skos:Concept in a taxonomy), then these should be defined in an ontology that gets included in the collections that need them. Inclusion is done on creation of an asset collection and, subsequently, additional ontologies can be included using Settings>Includes. Internally, inclusions are recorded using owl:imports statements.

Note that along with class-level definitions, the ontology editor still supports instances in a limited manner, which might be needed in certain cases such as small enumerated values.  You will only be able to define label and comment for these instances. Note, you will see a warning when creating a new instance in the Instances Panel of the editor. Ontologies should only contain shape-related assets but not instances. You may proceed creating small numbers of simple instances, for example to represent enumerated values. However, all fields of those instances except labels and comments will be marked as read-only. You are strongly encouraged to store instance data in non-Ontology asset collections such as Data Graphs.

How-to Guidance

Refactoring Ontologies

If you have an ontology that contains both schema and instances or a file that contains both and you want to separate them, the option on the Transform tab>Copy or Move Instances from Other Asset Collection lets you separate instances from schema definitions.

Create an asset collection that should contain the instances if one does not exist already. Navigate to its Transform tab and select Copy or Move Instances from Other Asset Collection. In the displayed dialog, select the ontology that currently contains instances. Then, select classes which instances you want to move.

Example: You may have RDF file that contains classes, properties as well as instances and you want to separate them. Create an ontology in EDG and load RDF file. Create another asset collection such as Taxonomy, Reference Dataset or Data Graph. Base it on your ontology. Use Copy or Move Instances from Other Asset Collection to move instances to it from the ontology.

Converting non-SHACL ontologies

EDG uses SHACL in ontologies to describe characteristics of class instances e.g., what properties they may have and what type of values are expected for the properties.

Non-SHACL ontologies can be converted to SHACL via the ontology utility:  Transform > Convert OWL Axioms to SHACL Constraints. It gives you a choice of keeping OWL statements and adding SHACL or replacing OWL with SHACL. Majority of RDFS/OWL will be converted. However, some of the complex OWL axioms may require further manual translation.

Automatic translation is described in this blog. However, the blog reflects a “point in time” status of the translation. What is translated may be periodically extended. To gain the most up to date knowledge on what and how is translated, take a look at the files in the EDG’s workspace that contain translation rules. They are called shacl2rdfs.sahapes.ttl and shacl2oel.shapes.ttl.  If desired, you can modify them to extend the transformation capabilities.

To add SHACL declarations to a class that is not yet defined to be a Node Shape, select it and then use Modify  > Enable SHACL constraints for this class.

Working with Classes

Classes describe characteristics (properties) of class members or instances. For example, a class Person is used to describe what properties a person may have e.g., first name, last name, data of birth, etc. In EDG, classes are typically created in the Classes panel using either Add (create) New icon at the upper left of the panel or Modify > Create subclass menu option. Also see information in Creating New Assets and Classes Panel.

Classes are organized in hierarchies. Each class will have a parent or superclass. Relationship between a child and a parent class is  rdfs:subclassOf.  These relationships can be modified on the class’s form to change a class’s parent. Select a class in the Classes panel. Once it is displayed on the form, change the “superclass” value by entering a new one. You can also change a class’s parent by dragging it in the hierarchy displayed in Classes panel. A class can have multiple parent classes.

Any property defined for a parent class appears on the form for the child class as “inherited” property.

Creating Abstract Classes

Sometime, you may need to define classes that have no direct instances. Instead, their instances are always members of  subclasses. For example, in EDG ontology for data assets, there is a class Data Asset. It is an abstract class with many subclasses such as Database, Dataset and numerous others. When creating instances, EDG will not let you create an instances of an abstract class and, instead, will make you select one of its subclasses.

To define your class as abstract, set the value of abstract to true.  Internally, this is stored using dash:abstract property.

Creating Node Shapes

Node shapes are used to describe characteristics (properties) of other resources. This sounds similar to classes and, indeed, a class created in EDG will also be a node shape. However, there are also node shapes that are not classes. Unlike classes, these node shapes do not have any members. Such shapes define characteristics of resources that are “targeted” by a shape.  There are various ways to specify shape’s target. Targets of a node shape that is also a class are always members of the class.

To create node shapes that are not classes, use either Add (create) New icon at the upper left of the Node Shapes panel or right click and use Modify > Create subshape menu option.

Also see information in Creating New Assets and Node Shapes Panel.

Creating Properties and Property Groups

The starting point for creating properties is selecting a class/node shape. With a class/node shape selected you can:

  • Create a property by using Property Groups panel. See  Property Groups Panel for more information and examples. This panel also lets you create new property groups that will organize properties into form sections.
  • Create a property directly from the form displaying a class or a node shape – as described under Form Panel (schema assets).

When you use either of these options, EDG will create a new property shape associating it with a class. By default, EDG will simply reference the property by using sh:path in the property shape. No other statements will be created for the property itself. This is done to ensure that when a property shape is deleted, no unused property declarations remain. And to ensure that there is no discrepancy between a property and property shape in terms of its  display name and description.

When creating a property shape, EDG will generate its URI by combining QName of the selected class/node shape with the property name you enter in the create dialog e.g., if you select a class with the Qname example:Country and enter population as the property name, TopBraid EDG will create a property shape with the Qname example:Country-population and will set the value of its sh:path property to example:population. Thus, we get a property shape example:Country connecting a class example:Country with a property example:population.

This means that the property shapes created using these methods can be fully referenced and re-used in the ontology they are created in or in other ontologies. If you want a property shape to be created as a blank node, you can press None button to the right of the ID of Definition field in the Create dialog.

The Create dialog will let you select the most commonly used constraints for the values of the property (e.g., cardinality and type of values).  After the property shape is created, you can add more information as described under Property Shapes Forms. This information will guide how values of a property are displayed on a form, how they are available for query and how they will be validated.

The default mode of property creation can be modified in the Manage tab by checking Also create global OWL Properties option. If this option is activated, EDG will also  produce an owl:DatatypeProperty or owl:ObjectProperty for a property when creating a new SHACL property shape. If you delete all property shapes referencing a property and want to remove all statements about the property, navigate to the property (e.g., by using RDF/OWL Property List panel or by looking up the property by QName or URI) and delete it as explained under Deleting Properties.

Finally, you can create a property by clicking New on the RDF/OWL Property List panel. This action will not create a property shape.

Creating Property Shapes for already Existing Properties

There are several options for accomplishing this.

One option is to first, identify the URI of the property you want to create a shape for. It is best to copy it into the copy buffer. Then:

  • Click on Create Attribute or Create Relationship – as appropriate.
  • In the create dialog, make sure that Show Identifiers is checked. In the ID/Path of Property field, copy the URL or the Qname of the property. You could also see CTRL-Space to auto-complete existing property identifiers.
  • Enter any display characteristics (name, description, group, order) and constraints.

If the property has a type statement i.e., it would show up in the RDF/OWL Property List panel, you can also click on the button to the right of the ID/Path of Property field  – it will let you look up the property by name.

Another option is to re-use an already existing property shape. This can be done by using Add existing property definition … option in the Property Groups panel. You will need to start typing the Qname of an existing property shape and then pick it from the list – as shown below.

This action will associate your selected class/node-shape with an already existing property shape. In other words, the same property shape will be used in two places and any modifications you make to it would be effective in two places.

Yet another option is to copy a property shape and modify the copy.

For example, you could select a property shape, clone it and then associate the clone with a class different from the class associated with the original shape (this will require you updating two classes: the class that the original shape was connected to and the class that a clone should be connected to).

Or you could select a class/node-shape and then select Modify>Clone property shapes from …

See Property Groups Panel and Classes Panel for more information.

Creating Property Shapes from Spreadsheet Columns

Select a class/node shape for which you want to import property definitions. Then select Modify>Add property shapes from Spreadsheet columns … .

The input spreadsheet must have at least two rows. The top row must list properties. Other rows should contain data.

Select a file and click on Upload. You will see mapping options as shown below.

  • Deselect any column for which you do not want to create property definitions
  • Optionally, change Property IDs – they will be pre-filled from the column names
  • Optionally, adjust Property Type. EDG will guess the type based on the data in the spreadsheet. Adjust to indicate that a column represents a relationship. You will then need to select a class of the related resources. Your target class must already exist. Also adjust the property type to Label if a column contains names of your resources.

After mapping you can click on Preview to examine property definitions that  will be created and or click on OK to execute.

Creating Classes and Property Shapes from Data

If you have data that contains property values for which no property shapes exist in an ontology, TopBraid EDG can auto-generate property definitions. Data that will be analyzed must be located in one of the asset collections.

Select a class for which you want to import property definitions. Then select Modify>Derive property shapes from instances … .

EDG will display a dialog where you will:

  • Identify an asset collection containing data
  • Specify the max number of instances to analyze – default is 1,000
  • Optionally, specify a Property Group for the newly created properties

You can also create missing classes and property shapes for multiple classes at once by clicking on the Home icon for an ontology and using Modify>Derive missing classes … This operation will create a SHACL class for each type used in the data. It will then create property shapes for each class.

Creating Inverse Relationships

Relationships are always directional. For example, the column of relationship goes from a Column to a Table that contains a column.  Using it, you can, for example, say that Customer ID is a column of Customer Master Table.

Sometimes, you may want to name (give a label) to a relationship that goes into another, inverse direction. You may want to display on the form showing information about Customer Master Table all its columns. Strictly speaking you do not need to do anything to see this information in the EDG UI as you can use the References panel to show all incoming links for any asset. Nevertheless, there are situations where you may want this info to be displayed in line with other data and/or want to search on this information.

To give a name to the inverse connection, click on the property shape for which you want to create an inverse, then select Modify>Declare inverse property … . You will get a dialog where you can specify a name for the inverse e.g,  “columns”.  Now, you will see that there is columns relationship from a Table to Column and if you go to, for example, Customer Master Table, you will see columns:  customer ID.

The data is stored in only one direction but you will be able to see and edit it in both.

You can also create an inverse property by following the approach specified in the Creating Property Shapes for Complex Paths and enter “^” plus a Qname of a property e.g., ^edg:columnsOf.

This process does not create a new property, it only gives a human readable name to the inverse.

There are cases where you already have an inverse property with its own URI and you want to use it. In this case:

  • Click on Create Relationship
  • In the ID field provide the URI of the inverse property
  • Type the name of the relationship e.g., columns
  • Provide a description, display and constraint information just as you would normally do

In this case, EDG will create a property shape, but there will be no connection between let’s say edg:columnsOf and edg:columns. When editing, you will be able to populate links in both direction, but they will not be synchronized.

To define a connection, create a Property Value Rule that will calculate values for let’s say edg:columns based on the values for edg:columnsOf. The underlying SHACL expression will look as follows:

 

sh:values [

                        sh:path [

                                    sh:inversePath edg:columnOf ;

                                    ]

                        ]

When you define a rule, the inverse (e.g., edg:columns) becomes a calculated or inferred property. You will not be able to enter its values nor will EDG store values for the edg:columns property. Instead, it will generate them on demand at query time. You can query for them and, if necessary for external systems, you can run the rule (use Transform tab) to populate these values for export.

Setting a Primary Key for a Class

Primary key constraint tells EDG how to generate URIs for class members. EDG will use values of a property selected in the constraint and pre-pend to them a string you specify as the “URI start”. This constraint takes priority over the URI construction method set for an asset collection.

A property that has a primary key constraint is expected to have unique values across all instances of the class. When you create a new member of a class, if it has a primary key constraint, EDG will always ask you to provide a value for the primary key.

To set a primary key constraint on a property, select the appropriate class in the Class Panel, then select the property in the Property Groups Panel. The Form Panel will refresh allowing you to edit constraints for the property. Find URI start on the form, enter the beginning of the URI pattern that will be used to construct the individual URIs e.g., http://example.org/MyClass-. Click Save Changes.  URI start value must be such that combining it with the values of the property you selected will generate valid URIs.

To use a class as the main entity of any reference dataset, the class must have exactly one property designated with the primary key constraint, which may be specified either on the class itself or on one of its superclasses. 

Creating Shapes for Complex Property Paths

Sometimes, you may want to define a connection between an asset and another asset or a literal (e.g., a string or an integer) value using a complex set of connections. Property paths support retrieval of information that is connected to a given asset through a chain of relationships.

For example, a grandparent is a parent of a parent. Country of birth, can be thought of as a relationship that traverses a connection between a person, a city/town they are born in and a country the birth city belongs to. Financial applications often ask applicant to provide a maiden name of their mother. “Mother’s maiden name” can be reached by first going to person’s mother and then to mother’s maiden name.

To create a property shape for a complex property path:

  • Click on Create Attribute or Create Relationship depending on whether the final value in the path is a literal or another resource
  • In the create dialog, check Show Identifiers.
  • In the ID/Path of Property field, enter a path. You can use URIs or qname and enter property path expressions in SPARQL syntax. For example:
  • Enter ex:parent/ex:parent for a path expression to reach the grandparents of a person or ex:parent/ex:maidenName to reach a maiden name of a parent – this will deliver a value only for a parent that has a maiden name.
  • For inverse links use “^” e.g.,^ex:parent. This will deliver children of a person.
  • To say that a a given relationship may occur one or more times in a path use “+” e.g., ex:parent+.  This will deliver all ancestors of a person.
  • To say that a a given relationship may occur zero or more times in a path use “*” e.g., rdf:type/rdfs:subClassOf*. This will deliver a class that a given asset belongs to and, if this class has parent classes, will deliver all the parent classes.
  • To specify alternative paths use “|” e.g., skos:broader|^skos:hasTopConcept.  This will deliver, for a concept, either a broader concept or, if it is a top concept of a concept scheme, a concept scheme.
  • Use CTRL-Space to auto-complete existing property identifiers.
  • Enter the rest of the information as usual (e.g., name, datatype)

Enabling Reification of Property Values

Sometimes, you may want to capture facts about property values. The modeling pattern that supports doing this is typically called reification. You may have a statement such as Joe’s job title is Software Developer. You want to be able to make other statements about it. In order to do this you need to give an identity to  Joe’s job title is Software Developer statement. This is what reification means. One may say that they want to reify people’s job titles in order to, for example, capture a source of a statement about Joe’s job title or its effectivity date.  To specify this in an ontology:

  • Create a Node Shape e.g., Effectivity Shape
  • Add to the node shape properties to store facts you want to capture e.g effective start and effective end dates
  • Navigate to a class which property values you want to annotate with these facts e.g., class Person
  • Select a property for which values you want to capture the effective start and end e.g., job title property. Edit it and scroll down to the Reification (Statements about Statements) section to add the node shape (e.g., Effectivity Shape) as a value of the reifiable by property. Internally, this is stored using dash:reifiableBy property

Now, when you use the ontology as the basis of another asset collection (such as a data graph or a taxonomy or a reference dataset), you will be able to add effective dates to statements that store job titles of people.

Most constraint components now have the ability to reify triples as shown in following example. These local message and severity will override the message and severity defined at shape level.

For more technical details and RDF syntax for reified values see DASH Reification Support Specification.

Enabling Indexing of Property Values

You can specify that property values should be ordered. To do this, select a property. Edit it and scroll down to the Reification (Statements about Statements) section to set its indexed constraint value to true.

Index starts with 0. This should be set only for properties with values stored by EDG i.e., values are not calculated.

Working with Rules

SHACL Triple and SPARQL Rules can be created using the Source Code panel. For more on SHACL Rules, see W3C SHACL Advanced Features Specification https://www.w3.org/TR/shacl-af/.

You will also be able to create a Property Value Rule from a template or by editing the source code and you will be able to set default values for a property.

Property Value rules are used by EDG to dynamically calculate (infer) values for the selected property.

With a property shape selected, click on Modify and pick the option to create property value rule from template:

When you select a template, you will be able to enter additional parameters. For example, if you want to populate a number of related concepts for a selected taxonomy concept:

  • Create a new attribute e.g., “number of related concepts”
  • Select it and using Modify>Create property value rule …
  • Select Count number of properties template
  • Type “related concept” in the template field or pick it from the dropdown
  • Press OK

You will see the following rule in the Inferences section.

The source code will show the following.

You can edit the source code to create more complex rules than those covered by available templates. Power users can also define additional templates to cover your most common rule patterns.

Now, if you navigate to a taxonomy based on this ontology, you will see a number of related concepts – as shown below.

Calculated (inferred) fields are not editable.

You can set a default value using a similar approach. Default value can be a constant or an expression such as ones using for sh:values field. There is no form-based UI for entering default values. Use source code and sh:defaultValue. For more information see https://www.topquadrant.com/graphql/values.html 

Working with Wikidata and other external Knowledge Graphs

For classes and node shapes, you will be able auto-create property shapes using Wikidata resource as an example.

To do this, use an option under Modify menu and provide an ID of a resource from Wikidata. EDG will return its properties for selection. You will be able to select the ones you want to use.

For property shapes, you will be able to create Wikidata link (or a link to another SPARQL endpoint) by selecting an option under Modify menu. The form will not change, but in the source code you will see “dash:detailsEndpoint https://query.wikidata.org/sparql”. You can use Source Code panel to make links to other endpoints.

Whenever a property shape carries a value for dash:detailsEndpoint, TopBraid EDG will understand that the values of the property are URIs and that more statements for these URIs can be queried from the given SPARQL endpoint. If the endpoint happens to be exactly the URL above, then additional features for Wikidata get activated. For more on how to use this feature, see this tutorial https://www.topquadrant.com/technology/shacl/wikidata/.

Deactivating Property Shapes

Click on the property shape you want to deactivate, then click Edit. Select “true” in the deactivated dropdown. Internally, this is stored using sh:deactivated property.

After you do this, you will no longer see this property and its values on the instances forms. If you still want to use the property and only wanted to deactivate some specific constraints, create another property shape using the same property and specify constraints you want to keep.

Creating Alternative Views

EDG lets you create different views into assets. This is accomplished by creating a Node Shape that is not a class and targeting it to the members of the class by using applicableClass target.

To quickly build a new view, clone property shapes from the “base class” selecting only properties you want to appear in each view. You can also add new properties, but typically, these should be inferred properties backed by rules. This is because the base class should normally already have all the applicable properties.

You can make an alternative view to be the default one for all users. Or you can specify it as a default for users in certain roles.

Deleting Classes and Node Shapes

Deleting a class does not remove its subclasses. If a child does not have any parents it will no longer appear in the Classes panel, but you will be able to find it in the Search panel and/or navigate to it using Navigate to… .

Deleting a class or a node shape does not delete associated property shapes if they are defined as independent resources with their own URIs. It will remove property shapes that are blank nodes.

Deleting Property Groups 

Deleting a property group does not remove any property shapes associated with the group.

Properties that used to be grouped under the deleted group will now appear under “catch all” Other Properties group.

Deleting Property Shapes

A property shape can be deleted using Delete action in the Modify menu.

If multiple property shapes are defined for the same property, deleting one property shape does not impact any other property shapes. Nor does such delete operation remove any data that may be using a property.

Deleting Properties 

Typically, it is sufficient to delete property shapes. If a property has any information associated directly with it (outside of what is in a property shape), it can be deleted by displaying it on a form and then selecting Modify>Delete.

Deleting a property does it remove any data that is using it.

SHACL Enablement

SHACL is a W3C constraint language that is used to define well-formedness conditions on RDF graphs (See also: introduction, tutorials: EDG, TBC).

EDG uses SHACL in ontologies to describe characteristics of class instances e.g, what properties they may have and what type of values are expected for the properties. 

Converting non-SHACL ontologies

Non-SHACL ontologies can be converted to SHACL via the ontology utility:  Transform > Convert OWL Axioms to SHACL Constraints. It gives you a choice of keeping OWL statements and adding SHACL or replacing OWL with SHACL. Majority of RDFS/OWL will be converted. However, some of the complex OWL axioms may require further manual translation.

To add SHACL declarations to a class that is not yet defined to be a Node Shape, select it and then use the gear menu  > Enable SHACL constraints for this class. 

Note: If your ontology contains instances, you need to generate SHACL shapes to fully use search over instances.  Otherwise, only free text search is available.

SHACL requirements for working with Reference Datasets and Data Graphs

Working with TopBraid EDG asset collections that use ontologies as their data schemas requires that classes that define the resources (assets) of interest are: 

  1. SHACL Node shapes and
  2. Declared to be public (or protected) classes/shapes of an ontology that defines them.

All necessary requirements are already addressed for the majority of collection types e.g., Taxonomies, Data Asset Collections, etc., – in other words, for any collection that is based on a pre-built ontology shipped with EDG.

Since Reference Datasets and Data Graphs are based on your own, custom ontologies, you will need to add the necessary information yourself. A class can be made public by adding it to the GraphQL public classes on the Form Panel for the collection.

 

For additional technical details behind these requirements see this page.

Note: If your property labels contain hyphens ( – ), you should give them a GraphQL field name without a hyphen. To populate GraphQL field name for a property, navigate to a property shape form and enter a value for “GraphQL field name”. GraphQL name is also required if you are defining a shape for rdfs:label. It should be rdfs_labe

Ontology Editor Panels

 

For a walkthrough of each panel of the editor, please read the Editor user guide as a prerequisite to this section. Ontology specific details are below.

You can add schema panels to an editor for any asset collection, but you will only be able to perform edit operations in these panels if you are in an ontology.

If you are in an ontology and some of the editing operations are not available to you, check that you have editing permissions. If you do, then a resource you have selected may be defined in an included ontology. In this case, some of editing is not possible i.e., you can add new statements, but you can’t delete statements that are from the included ontology.

Class Hierarchy Panel

This panel displays hierarchy of classes starting with a selected root. Hierarchical relationship between classes is rdfs:subClassOf. You can re-arrange classes in the hierarchy by dragging and dropping.

In EDG, every asset is a member of at least one class. Properties are associated with classes and a default view of the asset is determined by classes it belongs to. Alternative views can be defined by node shapes that are not classes themselves but target members of a class.

By default, the root class in the Classes panel is set to Thing. You can set the root to another class via Manage > Root Class of Hierarchy. This might be desired, for example, if your ontology specializes another ontology, and you don’t want to show the ancestor classes of your main custom class. Replace the default class-name “Thing” with the name of the preferred root class. Autocomplete will assist in entering the class-name.

Classes panel has a quick search field. It lets you look up classes displayed in the tree. The lookup is limited only to classes that are children of the currently selected root. The icon to the right of the Quick search field will switch from autocomplete lookup based on the label to the full text search across all string properties.

To create a new class, select the parent class and then click the Create Class…   button. Or, alternatively, right click on the parent and select Create subclass of … :

  • EDG will display a dialog box where you enter the name of your new Class and optionally edit the URI generated by EDG as an internal ID for the class.
  • By default, EDG will automatically generate a URI to uniquely identify the resource by combining the default namespace specified for the ontology on its creation (the default being “http://example.org/ontologies/<asset collection name>#”) with a user-entered label for the resource, with any characters that would cause problems in a URI being converted. For example, the URI generated for a class with the label “Nonprofit Organization” might be “http://example.org/ontologies/my_ontology#NonprofitOrganization”. If the generated URI is non-unique, EDG will give you a message that resource already exists.
  • After you click the OK button, EDG adds the class to the hierarchy.

Note: Every new class will also be typed as a SHACL Node Shape. If you have started by loading into EDG ontologies in RDFS/EDG, use Transform>Convert OWL Axioms to SHACL Constraints to generate SHACL Shapes.

This panel has no menu system in the header, instead actions are driven by right clicking on a class. It also has no settings menu.

Create Subclass

Lets you create a subclass of the selected class.

Add to Asset List

Adds selected asset to a sharable asset list. Asset lists are available in the Asset List Panel and used for bookmarking or bulk actions. 

Endorse Asset

Lets you add  Endorsement for the selected asset

Add to Basket

Basket is similar to Asset List but for all of EDG. It is located in the left navigation menu. Here you create create new versions of collection or bookmark assets or collections. This is per user and not shared. 

Open in new Browser tab

This opens the new browser tab displaying the selected asset.

Open in new Form

This opens the Form Panel for the selected asset.

Start Workflow

Starts a workflow for this selected asset in this collection.

Explore Menu

Provides access to the following operations:

  • Find Similar Assets … – will open a search dialog to select similarity criteria
  • Find Usages in Other Assets Collections … – will find other asset collections that reference selected asset
  • Show Affected Workflows … – will check if any active workflows contain any changes to the selected class
  • Show Comments … – will let you view already created comments for the selected class and will let you create new comments
  • Show Endorsements … – will let you view who endorsed this asset
  • Show Tasks … – will let you view already created tasks for the selected class and will let you create new tasks
  • Show NeighborGram – will display NeighborGram panel for selected class
  • Show Relationship Tree – will display Relationship Tree panel for selected class

Modify Menu

 

Provides access to the following operations:

  • Clone … – will clone selected class. All property shapes associated with the selected class will also be associated with the clone. See Cloning and Replacing Assets for more.
  • Merge … – will remove the selected class and copy all its information into another, “merged into” class. Not available for classes included from another ontology.
  • Replace … – will replace selected class. See Cloning and Replacing Assets for more. Not available for classes included from another ontology.
  • Add Label Property Declaration – will auto-create a property shape for rdfs:label. Only available if a class is also a node shape.
  • Clone property shapes from … – will let you select a class or a node shape from which to clone property shapes definitions. You will be able to select the properties to clone. Cloning creates copies of selected property shapes as blank nodes. Only available if a class is also a node shape.
  • Derive property shapes from instances … – will let you select an asset collection that contains instance data for this class. It will examine the data and automatically create property shapes based on the data values. Only available if a class is also a node shape.
  • Add property shapes from Spreadsheet columns … – will let you select a spreadsheet to use as an indicative example from which to create property definitions. Only available if a class is also a node shape.
  • Add property shapes from Wikidata sample … – will let you identify Wikidata resource to use as an indicative example from which to create property definitions. You will be able to select properties you want to use and modify their cardinalities and datatypes. New property shapes will be created as resources using the standard Class-property convention for URI creation. Only available if a class is also a node shape.
  • Delete … – after confirmation, will delete the selected class. It will also delete some associated items. Deleting a class will delete all its instances if they are present in the ontology. Any property shapes will be deleted if they are identified using blank nodes. For more information see Deleting Assets. Not available for classes included from another ontology.
  • Delete with subclasses … – after confirmation, will delete the selected class and all its subclasses, transitively. Not available for classes included from another ontology. Only available if a class has subclasses.
  • Enable SHACL constraints for this class – only available if selected class is not already a node shape, will add a type statement making a class also a node shape

Node Shapes Panel

While EDG will declare all new classes also as Node Shapes, it also supports creation of Node Shapes that are not classes. This may be useful when creating an alternative view of class members or when creating a shape that will be used in other shapes, for example, as part of logical expressions.

Node Shapes panel displays ONLY node shapes that are not classes. It also supports creation of such shapes. This means that in order for these shapes to be used with data, they must be targeted. See W3C SHACL specification to understand targets https://www.w3.org/TR/shacl/#targets.

This panel can display hierarchy of node shapes. Hierarchical relationship between node shapes is sh:node. You can drag and drop node shapes to arrange them hierarchically. Organizing a node shape under a parent means that all constraints defined for the parent apply to the child.

Node Shapes panel has a quick search field. It lets you quickly look up node shapes of interest. Lookup will only search for node shapes presented in this panel i.e., no classes. The icon to the right of the Quick search field will switch from autocomplete lookup based on the label to the full text search across all string properties.

Right clicking on a Node Shape, in addition to create action, will give you access to Explore and Modify operations. All operations are described below.

Create Subshape

Lets you create a subshape of the selected shape. Internally, relationship between a child and parent shape is stored using sh:node.

Add to Asset List

Adds selected asset to a sharable asset list. Asset lists are available in the Asset List Panel and used for bookmarking or bulk actions. 

Endorse Asset

Lets you add  Endorsement for the selected asset

Add to Basket

Basket is similar to Asset List but for all of EDG. It is located in the left navigation menu. Here you create create new versions of collection or bookmark assets or collections. This is per user and not shared. 

Open in new Browser tab

This opens the new browser tab displaying the selected asset.

Open on new Form

This opens the Form Panel for the selected asset.

Start Workflow

Starts a workflow for this selected asset in this collection.

Explore Menu

 

Provides access to the following operations:

  • Find Similar Assets … – will open a search dialog to select similarity criteria
  • Find Usages in Other Assets Collections … – will find other asset collections that reference selected asset
  • Show Affected Workflows … – will check if any active workflows contain any changes to the selected asset
  • Show Comments … – will let you view already created comments for the selected asset and will let you create new comments
  • Show Endorsements … – will let you view who endorsed this asset
  • Show Tasks … – will let you view already created tasks for the selected asset and will let you create new tasks
  • Show NeighborGram – will display NeighborGram panel for selected asset
  • Show Relationship Tree – will display Relationship Tree panel for selected asset

Modify Menu

 

Provides access to the following operations:

  • Clone … – will clone selected node shape. All property shapes associated with it will also be associated with the clone.
  • Merge … – will remove the selected node shape and copy all its information into another, “merged into” shape. Not available for node shapes included from another ontology.
  • Replace … – will replace selected node shape.  Not available for node shapes included from another ontology.
  • Add Label Property Declaration – will auto-create a property shape for rdfs:label.
  • Clone property shapes from … – will let you select a class or a node shape from which to clone property shapes definitions. You will be able to select the properties to clone. Cloning creates copies of selected property shapes as blank nodes.
  • Derive property shapes from instances … – will let you select an asset collection that contains instance data for this shape. It will examine the data and automatically create property shapes based on the data values.
  • Add property shapes from Spreadsheet columns … – will let you select a spreadsheet to use as an indicative example from which to create property definitions.
  • Add property shapes from Wikidata sample … – will let you identify Wikidata resource to use as an indicative example from which to create property definitions. You will be able to select properties you want to use and modify their cardinalities and datatypes. New property shapes will be created as resources using the standard property convention for URI creation.
  • Delete … – after confirmation, will delete the node shape. It will also delete some associated items. Any property shapes will be deleted if they are identified using blank nodes. Not available for node shapes included from another ontology.

Property Groups Panel

This panel will display properties associated with a selected class or a node shape. Properties are displayed organized into groups, reflecting how they would be shown on a form. If a property does not belong to any group, it will be shown under built-in Other Properties group. The panel lets you create new property definitions (for attributes and relationships) and new property groups. Properties are associated with classes (or node shapes) using property shapes which define constraints on the property values. It is possible to refer to the same property in multiple property shapes. Thus, this panel actually displays property shapes – associations between properties and classes/node shapes.

Create New dialogs will create a property shape, associating a property with the class/node-shape and containing value constraints. It will refer to a property that will be used by data, but, by default, it will not create any statements about the property other than the reference in the shape. If “Also create global OWL Properties” on the Manage tab is enabled, it will create a type statement for the property.

Alternatively, as described below, an existing property can be used to create a property shape.

The dialogs let you enter a name by which the property will be known in the context of the shape, its textual description and select its cardinality. For attributes, you will also be able to select the datatype (e.g., string, integer). Multiple datatypes can be selected. One common combination is string and langString. This leaves the choice of language tagging a value up to to the user that will enter data.

If you do not select a datatype, EDG will add a node-kind constraint indicating that the value is literal.

If you start the create process by selecting a property group, it will already be pre-selected in the dialog. Otherwise, you can choose one from the drop down or leave the selection empty.

For relationships, you will also be able to select a class values should belong to and/or a node shape they should comply with.

Clicking on the “i” icon in the upper right corner of the dialog will provide a description and instructions for each field in the dialog.

By default, EDG will automatically generate a URI to uniquely identify the resource by combining the default namespace specified for the ontology on its creation (the default being “http://example.org/ontologies/<asset collection name>#”) with a user-entered label for the resource. Any characters that would cause problems in a URI are converted. When creating property shapes, URI of the class and the name specified in the create dialog will be used to create the URI for the property shape

For example, if the property name is “new relationship” and it is created for a class with the URI “http://example.org/ontologies/my_ontology#MyClass”, the property shape will have the generated URI of “http://example.org/ontologies/my_ontology#MyClass-newRelationship”.

To override the system generated URIs, check Show Identifiers checkbox. The dialog will now show two new fields that can be updated:

  • ID/Path of Property
  • ID of Property Shape Definition

You can use these fields to override the generated URIs, to use URI of already existing property and to define properties that represent more complex connections between resources. The latter is done by entering path expressions in the ID/Path of Property field.

The other two options in the Property Groups panel let you add existing property group for use with your properties and add existing property shape to a selected class.

Property Group Operations

If you right click on a property group displayed in this panel, EDG will display the right click menu with the following options.

Create Attribute

Lets you create a property shape for an attribute, placing it within the selected property group.

Create Relationship

Lets you create a property shape for a relationship, placing it within the selected property group.

Add to Asset List

Adds selected group to a sharable asset list. Asset lists are available in the Asset List Panel and used for bookmarking or bulk actions. 

Add to Basket

Basket is similar to Asset List but for all of EDG. It is located in the left navigation menu. Here you create create new versions of collection or bookmark assets or collections. This is per user and not shared. 

Endorse Asset

Lets you add  Endorsement for the selected asset

Open in new Browser tab

This opens the new browser tab displaying the selected asset.

Open on new Form

This opens the Form Panel for the selected asset.
3Start Workflow

Starts a workflow for this selected asset in this collection.

Explore Menu

Provides access to the following operations:

  • Find Similar Assets … – will open a search dialog to select similarity criteria
  • Find Usages in Other Assets Collections … – will find other asset collections that reference selected asset
  • Show Affected Workflows … – will check if any active workflows contain any changes to the selected asset
  • Show Comments … – will let you view already created comments for the selected asset and will let you create new comments
  • Show Endorsements … – will let you view who endorsed this asset
  • Show Tasks … – will let you view already created tasks for the selected group and will let you create new tasks
  • Show NeighborGram – will display NeighborGram panel for selected group

Modify Menu

Provides access to the following operations:

  • Clone … – will clone the selected group. All property shapes associated with the selected group will also be associated with the clone.
  • Merge … – will merge selected group with another group
  • Replace … – will replace selected group.
  • Delete – after confirmation, will delete the selected group. Deleting a group will not impact any properties. They will now be placed under the “catch all” Other Properties group

Property Operations

If you right click on a property displayed in this panel, EDG will display the right click menu with the following options.

Add to Asset List

Adds selected property to a sharable asset list. Asset lists are available in the Asset List panel.

Add to Basket

Adds the selected property to the basket for all of EDG located in the left navigation menu.

Basket is similar to Asset List but for all of EDG. It is located in the left navigation menu. Here you create create new versions of collection or bookmark assets or collections. This is per user and not shared. 

Endorse Asset

Lets you add  Endorsement for the selected asset.

Open in new Browser tab

This opens the new browser tab displaying the selected asset.

Open on new Form

This opens the Form Panel for the selected asset.

Start Workflow

Starts a workflow for this selected asset in this collection.

Explore Menu

Provides access to the following operations:

  • Find Similar Assets … – will open a search dialog to select similarity criteria
  • Show Affected Workflows … – will check if any active workflows contain any changes to the selected property
  • Find Usages in Other Assets Collections … – will find other asset collections that reference selected asset
  • Show Comments … – will let you view already created comments for the selected asset and will let you create new comments
  • Show Endorsements … – will let you view who endorsed this asset
  • Show Tasks … – will let you view already created tasks for the selected property and will let you create new tasks
  • Show NeighborGram – will display NeighborGram panel for selected property
  • Show Relationship Tree – will display Relationship Tree panel for selected property

Modify Menu

Provides access to the following operations:

  • Clone … – will clone selected property shape. The label of the clone (preferred label in case of SKOS Concepts) will be set as the label of original asset with “ Copy” post-pended to it.
  • Merge … – will merge this property shape with another property shape
  • Replace … –Replace, creates a clone of the selected asset using URI that you will provide and then deletes selected asset. One difference with the clone operation above is that the label will be the same as the label of the original asset, “ Copy” will not be post-pended. You can use this operation if you decide that you need to modify URI identity of a resource. EDG will automatically adjust all incoming and outgoing references. However, it will do so only for the currently selected asset collection. Other asset collections will not be updated. If they contain references to the asset you are replacing, you will see broken links. To understand possible impacts of delete operations see Deleting Assets section.
  • Declare inverse property … – For a relationship, it will create an inverse property shape.
  • Create property value rule from template … – will let you create a calculation (inference) rule for property values.
  • Make Wikidata link – for more information on this option see Working with Wikidata and other external Knowledge Graphs.
  • Delete – after confirmation, will delete the selected shape. Property values are not impacted. Since asset collections in EDG can include each other by reference, some care needs to be taken when deleting assets. Delete operation only deletes references to the deleted asset that exist in your current asset collection.  Deleting a property does not delete property values that are held in another asset collection.

Settings menu for this panel provides the following options:

  • Leave property groups closed – when checked property groups will be shown collapsed with the ability to expand them one by one
  • Show numeric order values – when checked, numeric order of a property within a group and the order of groups will be shown after the property name in parenthesis
  • Show defining shapes/classes – when checked, shape/class a property is associated with will be shown in parenthesis after its name and order value

 

Form Panel (schema assets)

See information in the Form Panel (any asset) in the Editor documentation since most of the form options described for instances also apply to schema resources.

A few additional options are available when working with schema level resources.

Class Forms

For classes you will be able to:

  • Define a class as abstract – no instances can be created
  • Define a class as hidden – it will not be presented in the Class Hierarchy panel, in the Asset Navigator in the Search panel or in other places where classes a selected e.g., when creating a new Asset.
  • Use Manchester syntax when editing certain properties. Note that in this syntax you need to surround property and class names using the ` character (not the plain ‘ apostrophe). While this feature is available, EDG is optimized for using SHACL and we recommend that the models are defined in SHACL. SHACL shapes are created automatically when you create new properties.

Node Shape Forms

For node shapes, including node shapes that are also classes, you will be able to:

  • See associated properties displayed in a table on the form and add a new property by clicking on the “+’ icon next the “declared properties” field – as shown in the screenshot below.
  • Create associated properties by cloning them from another class or a node shape by selecting an option under the Modify menu.
  • Use sample data from another asset collection to create property shapes – an option under Modify menu.
  • Use sample data from Wikidata to create property shapes – an option under Modify menu.
  • Use spreadsheet data to create property shapes – an option under Modify menu.
  • Set targets – this is available only for Node Shapes that are not classes.
  • Set a node shape as a default view for all user roles or for a subset of roles. If nothing is set, then the default view for members of a class is a node shape that is also a class.
  • Add label property declaration – autogenerate a property shape for rdfs:label path

Property Shapes Forms

For property shapes, you will be able to:

  • Deactivate a property shape. Deactivating a shape means that the field will not appear on a form, it will not be available for GraphQL query and no data validation will be performed for its values.
  • Hide a property. It will no longer appear on a form, but it will be available for GraphQL query and its values will be validated
  • Mark a property as “read only”. In this case, users will not be able to change it in the form. However, if they have access to source code editing, they will still be able to modify it.
  • Update a property group, a property belongs to and its order within the group. If no group is selected, then a property will be displayed under the default Other Properties section on a form
  • Change the order of appearance of a property within a group. If no order is selected, then properties are presented in the alphanumeric order of their labels. Order is numeric and can contain fractional numbers e.g., 1.05 will be displayed after 1.02.
  • Specify GraphQL field name – only needed if the property label contains characters that are illegal in GraphQL i.e.,hyphens ( – ). Otherwise, the field name is auto-generated if this value is left empty.
  • Select View and Edit widgets for property values. Typically, this is not necessary as EDG will auto-select the most appropriate widget based on the datatype for literal values. For relationships, the widget will be standard autocomplete. However, some specialized widgets are also available.
  • Add a display name and description for a property field on a form. If a name and/or description exist for both, RDF/OWL property and a property shape, property shape values take precedence.
  • Add and modify property value constraints. Available constrain differs for attributes (properties with the literal values) and relationships
  • Create Wikidata link (or a link to another SPARQL endpoint). For more information on this option see Working with Wikidata and other external Knowledge Graphs.
  • Create a property value rule from a template – an option under Modify menu.
  • Specify how a property may be reified – to enable adding information to a property.
  • Generate an inverse shape – only available for a relationship – an option under Modify menu.

Options you will see on the forms for property shapes will depend on the type of a property – attribute or relationship. Common options are displayed on the screenshots below.

 

For literal values (attributes), you will also see the following options:

For relationships, you will see the following options:

Not all constraints can currently be defined using Forms. For some constraints (such as Logical constraint components and Qualified value shapes), you will need to use the Source Code panel.

Customizing Forms for Classes and Properties

Sometimes you may need to add your own properties to the forms for system resources e.g., classes and properties. To customize the forms of system resources such as rdfs:Class/sh:PropertyShape etc, you have two options:

  • You can define alternative view shapes by creating a Node Shape, declaring for it any property you may want to add and connecting such Node Shape via sh:targetClass or dash:applicableToClass to rdfs:Class, owl:Class, rdf:Property or sh:PropertyShape. These alternative views will then be offered in the usual view shapes drop-down in the upper right of the form. If you select “merge views” in the form’s Settings menu, you will see your new properties added to the system defined form.
  • Extra fields can be injected into the default system forms that are currently living in metash.ttl by uploading a graph with base URI http://datashapes.org/metashx (or /genericx for the generic.ttl replacement). These should owl:import the base file that they extend and then simply add sh:property shapes.

Class Diagram Panel

The class diagram panel shows a visual representation of the class and properties and it’s connections. There are several diagrams to choose from in the panel.

 

 

Instances Panel

This panel is a table showing all instances of a class selected in another panel e.g., Class Hierarchy panel. New button lets you create new instances. While this panel is available in different editors, the main use of it is in the OntologY Editor where Search Results panel with its richer capabilities for working with instances is not available.

Note that while you could create an instance directly in an ontology, ontologies in EDG are not intended for working with instances. When you create an instance directly in an ontology, you will only be able to create and edit its label and comment information.  

RDF/OWL Properties List Panel

This panel is a table showing instances of rdf:Property class and its subclasses. New button lets you create new properties. The main use of the panel is to find properties that do not participate in property shapes. Creating a property in this panel will not create a property shape.

 

Managing Ontologies

 

Custom root-class

By default, the root class of the Class Hierarchy is set to Thing. You can set it to another class via Manage > Root Class of Hierarchy. This might be desired, for example, if your ontology specializes another ontology, and you don’t want to show the ancestor classes of your main custom class. Replace the default class-name “Thing” with the name of the preferred root class. Autocomplete assists in entering the class-name.

Global OWL Properties

If Also Create Global OWL Properties option is activated, then creating a new SHACL property shape will also produce an owl:DatatypeProperty or owl:ObjectProperty. In other words, a property participating in a shape will be given a type.

Declare a global property for each new SHACL property shape.

 

By default, this option is de-activated. Activating it will result in a situation where you delete property shapes, but a property declaration remains and will need to be manually deleted separately.

Other Management  Operations

See Asset Collection Management for information on other Manage operations.

Exporting Ontologies

 

There are export options to produce RDF serialization of the ontology, Publish it to Explorer and query it with GraphQL. See Exporting guide for more information on these options. There are also two export options specific to ontologies. They are described below.

Export Ontology as RDF Schema File

Available for ontology collections only. Produces a simple, approximated RDF Schema version based on locally defined classes and SHACL property shapes, for use in external tools.

Export Ontology as OWL File

Available for ontology collections only. Produces a simple, approximated OWL version based on locally defined classes and SHACL property shapes, for use in external tools.