Skip to end of metadata
Go to start of metadata

Page Contents

View or Edit

If an Ontology is associated with some governance area, every user with any governance role in this are will be able to view it, at least. For any other user to view or edit assets contained in an Ontology, a manager must use the Ontology's utilities > Users settings (see documentation) to grant them permissions.

Note that different workflows that process changes to an Ontology can have their own permission-profile settings (for background, see Workflow Overview: Permissions for Production Collections ...).

Edits made directly in an asset collection are visible to all other collections that include it and to any workflows. In contrast, edits made as part of a workflow are only visible within the working copy managed by the workflow until and unless workflow changes are committed.

Ontology Editor

Classes vs. Instances

Beginning in version 5.4, EDG implements the recommend practice that instances in asset collections should be separated from their class definitions, which are included via one or more ontologies. Only ontologies should define classes, properties, and shapes (SHACL constraints) and all other asset collection types (e.g., taxonomy, etc.) should contain only instances. If any non-ontology collection needs special classes (e.g., subclasses of skos:Concept in a taxonomy), then it should include them (via owl:import) from one or more ontologies.

Note that along with class-level definitions, the ontology editor still supports instances, which might be needed in certain cases. However, any manager of an ontology can use Manage > No-Instances Mode to block the further creation or modification of instances, allowing only the editing of classes and their properties (attributes, relationships, constraints). Separating instance collections from their ontology definitions provides flexibility in using the models. NOTE: EDG Administrators can disable this restriction via Server Administration > Setup - Server Configuration Parameters > Advanced Parameters  (see for details).


The editor view has three vertical panes, where the left and right panes can each be collapsed/expanded by clicking the shaded control section in the center of the vertical separator/border column. Mousing over most buttons pops up its function label.

  click image to enlarge

Class Hierarchy

The editor's left pane shows the hierarchy of classes with their properties (attributes, relationship, constraints) shown as nodes in the tree. If the ontology allows instances (see above), then the lower hierarchy pane has a sub-pane for managing instances of the selected class. Note that classes and properties that come from included models are represented by icons with muted colors. You will be able to add information to these items, but you will not be able to delete them or modify information that comes from the included model. The hierarchy shows up to 1000 nodes.

Custom root-class

The root class of a hierarchy can be set to a desired element via Manage > Root Class of Hierarchy. This might be desired, for example, if the ontology specializes a standard one, 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.

Quick search

The Class Hierarchy and Instance window each have their own quick search field. It lets you look up items displayed in the tree and items displayed in the Instance window. The lookup in the Class Hierarchy is limited to classes only. It doesn't support search for properties associated with classes.

Find class or property by text

The ellipsis button  opens a dialog for a general text-search of all classes or properties containing the given search string in any property. Clicking on a row tries to select that resource in the tree.

Hierarchy Nodes and Buttons

Colored icons on the tree represent classes, properties, and constraints: brown circles are classes, green rectangles are attribute properties, blue rectangles are relationship properties, and open-center rectangles are constraints. Lightly colored items are included from other ontologies, and darkly colored items are locally defined in the current ontology.

A class. Under the hierarchy root each of these is a subclass of its parent node on the hierarchy.
An attribute property of the class represented by the shape's parent node on the hierarchy.
A relationship property of the class represented by the shape's parent node on the hierarchy.
N/AProperty shapes (SHACL constraints) no longer explicitly appear as nodes in the hierarchy. They are represented in the detail forms of their applicable properties and classes. (See below for details.)

At the top of the class hierarchy, next to the quick search field, managers and editors of the ontology have colored buttons that let them create a (sub)class , an attribute property , a relationship property , or add a property constraint , to the selected class. After creating a property, one can set the range of its values. For an attribute property, these are typically data types, such as "integer" for an attribute "age"; for a relationship property, the range would be a class such as "Country" for a "country of birth" relationship.

If the ontology allows instances, then the bottom portion of the hierarchy pane will have the Instances of <CLASSNAME> pane. If the selected class in the hierarchy has any instances in this same model, then they will be listed here, and selecting any one of them will display it in the central details pane. Although instances do not appear in the hierarchy, managers and editors have the New button in the Instances pane, which creates an instance of the selected class within the ontology.

Creating a class

Use the hierarchy to create a new class by first selecting the parent class and then click the Create Class... button . This displays 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. After you click the OK button, EDG adds the class's node to the hierarchy and displays it in the central property-details pane where you can edit its properties and constraints.

Adding a property: attribute or relationship

After selecting a class on the Class Hierarchy, clicking the Create Attribute...  or Create Relationship...  button adds one of those properties to the selected class. EDG first displays a dialog box where you enter the name of your new property and optionally edit the URI generated by EDG as an internal ID for the property. After you click the OK button, EDG adds your new property to the Class Hierarchy and displays details about the property in an edit form on the right where you can edit these details.

After you define a new attribute or relationship property for a given class, you will see it as a custom property on edit and search forms for that class.

Adding a property shape

On either a class or one of its properties, clicking on the Add Property Shape...  button creates a SHACL constraint for the selected, or identified, property, and the shape is associated with the class. The shape is not represented in the hierarchy view, but its shown in the details view of the related property and class. When a property is selected, its shapes (if any) are listed in the details view, in the Local Property Characteristics section, labeled by each shape's class. When a class is selected, its shapes (if any) are listed in the details view, in the Constraints section, labeld as "property shapes". In either case, users can switch the details view to just the details of a single property shape by clicking on box that shows the desired shape. The shapes can also be edited within the details view, either within context of their associated property or class or from their own details view alone.

Viewing and Editing Information about an Asset

Information about selected asset is shown in a form, with fields organized organized into groups. To get to the details form, double click a row or select a row and click the details button. 

Checking data quality via Problems and Suggestions

When the Show Problems and Suggestions button  at the top of the form is selected, form will display any issues that are found with the selected resource together with suggestions on how to fix them. It will also display some additional facts TopBraid EDG finds with some degree of certainty - for example it may suggest a connection between a data element and a business term. You can then accept the suggestion or ignore it. When the Show Problems and Suggestions button  is de-selected, checking of values and making suggestions will happen only when information is modified and saved or when a user decides to run Problems and Suggestions report for the entire collection. This setting acts across all of the user's collections.

Editing Information about an Asset

The default viewing mode shows only the properties of an Asset that currently have values.


Users with sufficient permissions can edit information in two ways: (1) per individual property via the pencil icon  that pops up as the cursor moves over a property; (2) all information on the form by pressing the Edit button  at the top of the page. 

Clicking a property's popup pencil icon  lets you edit "inline" values of that property.

The Edit-button  opens all available properties for editing. Showing fields that have values and those that do not yet have values.

  click to enlarge

The Edit-button mode also lets you log a message with the saved changes.

NOTE: When finished with Edit mode, be sure to click either the Save Changes or the Cancel button.

Show History

The Show History checkbox at the top of the page toggles the display of all saved changes made to the asset since it was first created. It lets you to undo or "revert" the changes back to what they were previously.


Editing Classes

When a node is selected in the hierarchy (class, instance, property, constraint), its details appear in the central pane, which lists actions for viewing, editing, etc., according to the user's permission profile for the collection. The top of the details pane has a button bar with the user's actions.

Actions for <class>

This has items for additional viewing, cloning, and customizing of the property layout for forms.
Visualization actions for <class>

This lists any graphical views (e.g., Neighborgram, etc.) that are pertinent to the selected item.
Show Problems & Suggestions

This toggles on/off the dynamic application of SHACL constraints (shapes) relevant to the item. Note as of 6.0, this is experimental; it might impact performance.
Open in new browser tab

This creates a new browser-tab of only the currently selected item.
Edit / Save Changes, Cancel(button)These buttons toggle the details center pane between view and edit modes. Viewing shows only properties with values while editing shows all potential property settings.
Delete(button)After confirmation, this deletes the selected item.
Print(button)This creates a page for printing the item's view.
Start Workflow(button)This creates a new workflow for this collection, which maintains a relationship to the selected item.

This lets you manage tasks associated with the item (see also: Ontology Utilities > Tasks View).

Note: this only appears if an administrator has activated the feature (see Administration: EDG Configuration Parameters).


This lets you associate comments with the item (see also: Ontology Utilities > Comments View).

Note: this only appears if an administrator has activated the feature (see Administration: EDG Configuration Parameters).

Show History(check-box)This displays the changes made to the item within its production or working-copy version, and it lets editors revert particular change steps.

Editing Properties

Like classes, selected properties show details in the center pane for viewing and editing. In the edit mode, properties (i.e., attributes or relationships) have numerous potential characteristics and constraints that can be set. (Note: A property's Open in new browser tab  option shows additional Annotations and Property Axioms.)

For example, when editing an attribute or relationship property, its domain identifies the class(es) with which it is associated (for example, which class forms the property will appear on), and the property's range identifies the potential values (datatypes or instance-types/classes) that can be assigned. Optionally, a property can also require value-settings by choosing a cardinality option from among those listed among the "Attribute Characteristics" or "Relationship Characteristics" on the editing form.

For example, the status relationship, below, has a domain of either the Country or the Market Identifier Code class and will thus status will appear as a property on forms for those classes and their instances, and it will limit values to those from its range, the Status class.

  click images to enlarge


Setting a Primary Key for a Class

By default, when creating a new resource (class, property, reference data item), EDG automatically generates a URI to uniquely identify the resource by combining the default namespace specified for the ontology (the default being "") 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 resource with the label "Pat Smith" might be "". If the label is non-unique, EDG will append a number to create a unique identifier.

If you are planning to use an ontology class as the main entity for any reference datasets (see Create New Reference Dataset), then each dataset must designate one of the class's properties as the primary key of its main entity. Using labels as identifiers is not sufficient for several reasons; e.g., there is no guarantee that they are all unique. Any property used as a primary key must have unique values across all members of the class, e.g., an employee ID or a social security number for People, or the ISO alpha-2 character code for Countries. If any datasets using the same main entity class also use different properties as their primary key, then each dataset must designate its own primary key. But if all such datasets use the same property as their primary key, then users have the option of designating the primary key once, on the ontology class itself.

To do this, select the property in the hierarchy pane and choose Make primary key... from the gear menu button  from the center-pane's bar. A dialog box will show a default URI that the property's value will be appended to, like this:

Set it to whatever you like, click the Ok button, and in the Class Hierarchy pane EDG will show that the selected property is now the primary key:

Then, when you create a new instance of that class, the dialog box where you enter the initial data will also ask you for a value of the primary key property. As you enter it, you'll see that value added to the URI that will be used to identify that resource during its lifetime:

Cloning a Class, Property, or Instance

Managers and editors can clone (copy) any existing class, property, or instance by selecting it, then clicking the gear menu button at the bottom of the central details pane. There is a clone action that will create a copy of the selected item. Note that cloning of a class will not include its subclasses.

Deleting Classes, Properties (attributes or relationships), and Instances

To delete a class, property, constraint, or instance select it in the hierarchy or instances pane and then select Delete... from its gear menu button in the details pane.

Deleting a property will also delete all values assigned to that property for all classes in the model. Deleting a class will recursively delete all of its properties, subclasses, and instances.

Changing a Class's Parent

In the Class Hierarchy, you can change a class's parent in order to refactor the class hierarchy. (This cannot be done for a class from an imported ontology, which will be represented with a lighter color circle on the Class Hierarchy.) Managers or editors can select a node in the Class Hierarchy, Edit it, and in the Class Characteristics section, they can change the sub-class of value by entering a new one:

The plus sign next to sub-class of means that you can add additional values for that property if you wish.

You can also change a class's parent by dragging it on the class hierarchy. In the following, Employee is being dragged, and the red X shows that the cursor is not yet in a valid new position for the Employee node of the tree:


With the mouse pointer on the Person class, it is a valid new position for the Employee class, as shown by the green check mark: 

Releasing the mouse button puts the Employee class at its new location:

Note that you cannot edit the class's parent class if it resides in an imported ontology.

Adding Constraints to a Class

NOTE: Constraints in TopBraid EDG are moving to the recent W3C recommendation: Shapes Constraint Language (SHACL) .  Users are encouraged to consult this tutorial on using SHACL in an ontology. For background, also see SHACL TUTORIAL: GETTING STARTED  (and this ).

As mentioned above, SHACL constraints now appear in the hierarchy as open-centered child nodes of their property (see the tutorial).

SPIN Constraints (deprecated)

EDG no longer lets you add new SPIN constraints to classes. If attempted, it will show message indication about using SHACL. To do so, select the desired class in the hierarchy view and then either: (a) click Add Property Shape..., to add a new SHACL-based constraint on a property of the class, or (b) click Edit in the class's detail view, which then shows any existing SHACL-based constraints.

Editing OWL Class Axioms

The Web Ontology Language (OWL) provides a notation called the Manchester Syntax that can be used to define restrictions on properties, intersections, unions and other logical class axioms. You can enter such expressions when you select Edit OWL class axioms from the drop down menu to the right of the input field for subclasses and equivalent classes. Note that in this syntax you need to surround property and class names using the ` character (not the plain ' apostrophe).

Displaying Relationships with NeighborGram and Class Diagrams

One can visually browse a resource's relationships to other resources (classes and instances) in an interactive graphical view called a NeighborGramTM. To launch this view from a resource's details pane, select the gear button  and select the Display NeighborGramTM... item. The views opens in a new browser tab.



When a resource node has many relationships, they will be shown in disjoint groups that are "pageable" via a selector with arrows and a counter. Selecting a node shows popup controls for making it the central resource, configuring links, or expanding links.

The form in the right pane shows details of the central resource. When that resource is a class, the form shows a Class Diagram section. Selecting that section link opens a nested form showing the class's associations in a UML-like diagram.

JIRA Launch-in-Context

If the JIRA LiC feature has been configured by an administrator, then for each asset collection, a manager can set an associated project-key string via Manage > JIRA Project Key (see documentation). Then, when the collection's editors are simultaneously logged into JIRA, they can launch from editor resources into related JIRA searches and new items in the collection's corresponding JIRA project. On a selected resource, use the gear button  in the details pane to select any of the following: Create JIRA Issue, Search URI on JIRA, or Search label on JIRA. The two searches will open (as browser popups) JIRA pages that search on the indicated resource string (URI or label). The create option will open the start of a new JIRA item. Note that if the browser is not logged into JIRA (or if the administered JIRA settings fail), then the launches can result in a Server Interaction Error.

Searching Within an Ontology

Basic Search Form

The basic search form provides many options in how you search and what you can do with your search results. For the selected class, the search form has a field for each property that you can add to it using the Filters dropdown in the upper right of the form. One can use a combination of fields to match instances only on those properties. Properties with two hyphenated fields allow one to search on a range of values. The Search any Text field matches on any property of an instance (See the Configuring Search Text Properties section in the Developer Guide for how to add this field to the search form for a given class and configuring which properties it should search). Each resulting instance must match all of the form's user-entered values (AND operator). Selecting Return local results only will deliver only resources whose rdf:type triple is in the base graph, thus excluding resources from included graphs. This search option will be presented if the vocabulary/asset manager has not pre-selected a choice.


Property matching

For each property, one can specify the type of match. Different properties can use different match types, all combining together to produce an overall search result.

Type of MatchHow a search value matches instance property-values
text contains

Text DEFAULT: Search text is a substring of a property- value (case-insensitive). Example: Search text "lis" on a city-name property would match instances having city-name values such as "Lisbon", "Lisboa", and "Minneapolis".

text equalsSearch text is exactly the same as a property- value (case-sensitive)
text matches regular expressionSearch text is a regular expression that matches a property-value (case-insensitive). Example: Search text "^lis" as a regular expression matches city-name values that begin with "lis", e.g., "Lisbon" and "Lisboa" but not "Minneapolis". Conversely, "lis$" would match only at the name's end.
any valueAt least one value exists for the search property (count >= 1). Example: See how extensively a property is used.
min/max number of valuesThe number (count) of property-values (occurrences) is within the search range, inclusive. Example: If most instances in a Ontology have labels in three languages, entering a label search with values-range 0 to 2 would return those instances with fewer.
no valueNo values exist for the search property (count = 0). Example: Use to clean up a Ontology and check for remaining work.
booleanBoolean DEFAULT: Search values restricted to true/false instead of free-text
equalsClass DEFAULT: Quick-search field for finding an instance of the property (object)
nested formAdds an embedded search form for properties whose type is another class
label matches regular expressionSearch text is a regular expression that matches the label of a property-instance (object)

Searching by relationship values

As you start typing a value in a relationship field, you will get a list of autocomplete options that match the text you've typed so far—a list of the names (labels) of any entities that begin with the typed letters.

The triangle next to each relationship field displays a menu that gives you several options for how EDG uses the value you enter in that field to search your reference data. The options are similar to the ones described above with a couple of exceptions: regular expression search is not available, but there is a nested form search option:

  • nested form displays a form denoted in dark gray where you can describe specific details about the items with the specified relationship to the data you're searching for.

  • label contains indicates that you want to search for codes that have the entered string anywhere in the label value for this resource. For example, if you search market identifier codes whose mic Country property has "land" in it, EDG will return resources with values such as Thailand, The Netherlands, and Switzerland.

  • any value indicates that you want to search for codes that have any value at all for this property.

  • min/max number of values search for any code whose number of values for this property fall in the range specified by the one or two numbers you enter.

  • no value indicates that you want to search for resources that do not have a value set for this property.

Displaying Columns in Results Tables

Columns in the results table are configured by properties

The columns displayed in the central results table are determined by a setting on each property in the search form. The display selector is located between each property's label and search field(s), and the display setting is independent of whether the property is used in a search.

This property will appear as a column in the results table
... (ellipsis)This property will not appear as a column in the results table
# (hash/number)

This property will appear as a count column in the results table (showing the number of property-values)

To change the table's columns, select or unselect fields in the search form (also see:  gear-button > Unselect all columns, below) and then press the Search button. The order of properties in the form determines the column-order of the table.

Setting the default columns

In subsequent editing sessions, the column settings will revert to their defaults. However, a manager can reconfigure the default for all users by selecting the columns and then clicking on the star button  at the bottom of the Search form. This preserves the current settings as the new default for all users.

A recommended practice is to set default columns (properties) on an ontology class, which is subsequently included by other vocabularies or assets, such as reference datasets. The resulting instance tables will have the ontology class's column settings as their initial default, which can then be overridden if desired.

Search Results Operations

The gear menu  below the search form gives you several options for what you can do with search results:

  • Batch edit search results... lets you edit property values for all the search results together. See Editing multiple codes together for further information.

  • Display chart of search results... generates a chart of your search results from your choice of formats.

  • Export results to SPARQL CSV spreadsheet creates a comma-separated value version of the search results that includes the URI of the resource represented by each result row in the first column. See the W3C SPARQL 1.1 Query Results CSV and TSV Formats standard for more details (although there aren't many more details—it's a very simple format).

  • Export results to SPARQL JSON file creates a text page of results in SPARQL Query Results JSON format.
  • Export results to SPARQL TSV spreadsheet creates a tab-separated value version of the search results that includes the URI of the resource represented by each result row in the first column. URIs are delimited by angle brackets.
  • Export results to SPARQL XML file creates an XML version of the search results that conform to the W3C SPARQL Query Results XML Format.

  • Export results to simple TSV spreadsheet creates a tab-separated value version of the search results, showing the preferred label of each resource instead of URIs. This creates a more human-readable version of the data than the SPARQL TSV spreadsheet.

  • Open faceted search dialog... displays a dialog box that lets you do a faceted search over the reference data for the selected entity.

  • Show SPARQL query... displays a pop-up window with the query that is being generated on the server when the search form is executed. Advanced users with knowledge of the SPARQL query language can copy and paste the resulting query string into a SPARQL execution window (for example, using TopBraid Composer) or send the query to the TopBraid Live SPARQL endpoint.

  • Unselect all columns clears all selected columns (check-marked or hash-counted) in the form, which removes all non-default columns from associated search-result tables.

Exported search results will be displayed in your browser. Select Save As from your browser's File menu to save the results as a text file.

Spreadsheet programs such as Excel can easily read tab-separated value files, so saving search results in a tab-separated format is a simple way to create custom reports for people with no access to your EDG installation.

Editing multiple results together

After executing a search with the search form, the Batch edit search results choice on the search form's gear menu  lets you edit all the search results at once with a single form.

For example, when selected after searching for all country codes that became valid in 1991, this menu choice displays the following form in a dialog box:

The form displays only values that all of the results have in common - in this case only the value for the "valid since" property. If you change this value, the change will apply to all resources in the search results. Any new values you will add will also apply to all search results.

Common values can be deleted all at once by clicking the X to the right of the value on the batch edit form, and new values can be added by entering them the displayed fields before clicking the Save Changes button.


Searching in No-Instances Mode

When the ontology is in the No-Instances Mode, the search form lets you find classes as opposed to their instances. You can also search for properties to find, for example, any property that has 'date' in its name or description. A dynamic icon on the search form's menu bar offers a way to toggle between the class search and property search.

Saving Searches

In the lower-right of the search pane, two buttons let you save and retrieve searches for later execution. In addition to executing these searches from within EDG, the saved search servlet lets other applications execute saved searches by using the appropriate URL. The "Save current search" button  displays a dialog box where you enter a name for the search that you'd like to re-use later. The "Show saved searches" button  displays a list of saved searches.

This dialog box has three buttons at the bottom:

  • The Select button closes the dialog box and fills out the search pane with the parameters set by the selected search so that you can execute it.

  • The Delete button deletes the selected search from the list of searches.

  • The Close button closes the dialog box.

Selecting a saved search on this dialog box also displays a URL in the Service URL (for copy and paste) field that can be used to retrieve the search results from another application that has HTTP access to EDG. This can be a browser, Excel (after picking Open from the File menu), or any application that can make a RESTful API call. (The default format of the returned data is comma-separated values, but this can be modified in the URL.)

Saved searches will also be available on the Export Saved Search list available via the Export tab.

Faceted Search

To do a faceted search for instances of the selected class, open the Faceted Search view through the gear button popup menu. The Add Property field lets one filter the instances based on their property values. (This does not show if there are no such instances.) Selecting Return local results only will deliver only resources whose rdf:type triple is in the base graph, thus excluding resources from included graphs. This search option will be presented if the vocabulary/asset manager has not pre-selected a choice.

Below, this field's drop-down list is being used to select the family name field.


In the next screen shot, the family name and gender properties have been added and the main form is showing information about the instances of the class. The > symbol to the right of the gender property has been selected, pointing it down and displaying all possible values stored with that property along with the number of instances that have those values. (Clicking the > to the right of the family name property would do the same for its values.)


Clicking "female" on the previous screen adds that as a faceted search criterion, so that the panel on the right only displays instances with a gender value of female:


Clicking the x next to "female" removes it as a search criterion, showing all the instances of the class that were shown before it was added. You can also narrow down the list of displayed names by entering a search string in the upper-left and clicking the magnifying class icon.

This example only scratched the surface of what you can do with faceted search. Using different combinations of properties and property values lets you do much more sophisticated searches of your instance data.

Editing form layouts

Please use SHACL constraints to customize form layouts. See the Developer Guide: Customizing Form Layouts.

  • No labels