Ontology Editor Overview
The editor view has three vertical panes, where the left and right panes can each be collapsed/expanded by clicking the "candy-striped" control section in the center of the vertical separator/border column. Mousing over most buttons pops up its function label.
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, which might be needed in certain cases. A user with manager privileges for 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). However, setting No-Instances Mode will prevent you from woking with Node Shapes that are not classes.
So, in principle, you could have an ontology that contains schema and and an ontology that contains instances only. However, while view and editing pages for ontologies support creation of instances, they are not as optimized for this task as are editing pages for other collection types.
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.
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. By default, EDG will assume the use of SHACL in ontologies, but for any particular ontology, its manager can switch this of. See Manage > Prefer SHACL over OWL/RDFS for details.
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:
- SHACL Node shapes and
- 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 selecting Edit, then in the GraphQL Schema section populating "public class of" property. Select the current ontology name from the drop down. Once you set this for a class, it is set for all its subclasses.
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 or rdf:type. It should be rdfs_label, rdf_type.
SHACL-based Instance Forms
EDG generates forms for viewing and editing class instances. 6.1 Release introduced new forms that are based on SHACL definitions.
In 6.1, these forms were experimental and required enabling in the Server Administration > Server Configuration Parameters. Starting with 6.2, these forms are used by default if SHACL definitions are present. Administrators can use Server Administration > Server Configuration Parameters to enable the previously used SWP/SWA-based form generation. When both form technologies are enabled, users will have an icon (in the top row of form icons) to switch between them. The choice is sticky.
- SHACL-based forms will show a property and its data values ONLY if a class used as the resource type (or one of its parent classes) has an associated shape for the property.
- This means that you need to make sure that there is a shape for every property used in your instance data (including rdfs:label). You will not see on a form any data that is not supported by property shapes.
- All ontologies shipped with EDG already use SHACL. Thus, asset collections based on them should not require any additional definitions. One exception is if you created some custom classes or properties and did not use SHACL to define them. In this case, you need to Transform > Convert OWL Axioms to SHACL Constraints.
- If you are using Reference Datasets or Data Graphs, ontologies describing their data must be defined in SHACL - as described above.
- Ontologies themselves do not use SHACL-based forms, not even for any instances contained in ontologies.
The editor's left pane shows the hierarchy of classes with their properties (attributes, relationships) 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 10,000 sibling nodes.
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.
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 buttonopens a dialog for a general text-search of all classes or properties containing the given search string in any textual 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.|
At the top of the class hierarchy, next to the quick search field, users with edit privileges for the ontology will see 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 define information about its values. For an attribute property, these are typically datatypes, 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:
- You will also see View Node Shapes button
- The bottom portion of the hierarchy pane will display 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.
By default, when creating a new resource class or property, EDG automatically generates 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#Nonprofit Organization. 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 and displays its form in the central pane where you can further edit its information.
Note: If Prefer SHACL over OWL/RDFS option under the Manage tab is checked, every new class will also be typed as a SHACL Node Shape. If Prefer SHACL over OWL/RDFS option is not checked but you want to make a class to also be a node shape, select Enable SHACL Constraints for this Class in the gear icon menu on the details pane. Further, if Prefer SHACL over OWL/RDFS option is not checked, you will be able to specify OWL axioms for the class.
Creating 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 a form in the central pane where you can further edit its information
What information is auto-generated when a property is created and what is shown in the details pane depends on whether Prefer SHACL over OWL/RDFS option under the Manage tab is checked or unchecked. By default, it will be checked.
When it is checked, creation of a new property will also generate a property shape connecting the property with a class which members will have property values. You will be able to specify your constraints directly on the property form.
When Prefer SHACL over OWL/RDFS is unchecked, creating a new property will generate a domain statement connecting the property to the class with which it is associated. You will be able to specify the range of the property and select from two options about the allowed number of values for this property.
After you define a new attribute or relationship property for a given class, you will see it appear on the edit and view forms for any member of that class. It will also be available for selection in the search and filter operations.
Creating a property shape
As described above, EDG will automatically add a property shape when a property is created if you are working in the Prefer SHACL mode. However, sometimes, you will need to create a shape for already existing property or create a shape that uses a a chain of properties.
If a property you want to use already exists, you can associate it with a class by selecting a class and clicking the Add Property Shape...button. This operation is also used to define constraints not for a direct value of a property, but for a value that is reached via a complex path or properties. This could be an inverse direction - there is a check box option of using inverse for convenience. Or it could be any combination of paths that you can enter by switching to the tab for any property-path expression. Path expressions are specified in SPARQL path syntax (including prefixes).
The resulting shape will appears in the form view of the related property and class.
- When a property is selected, its shapes (if any) are listed in the form view, under the Local Property Characteristics section, labeled by each shape's class.
- When a class is selected, its shapes (if any) are listed in the form view, under the Constraints section, labeled as "property shapes".
In either case, users can navigate, if needed, to a specific property shape by clicking on the light grey box surrounding the desired shape. Most of the shape information can also be edited on the form of their associated property or class.
Note: If you want labels to show up on the forms for your class instances, you need to declare a property shape for rdfs:label. You also need to add GraphQL name for it. Navigate to the property shape form and enter rdfs_label (with the underscore) in the GraphQL field name field.
Creating a node shape
While EDG will declare all new classes also as Node Shapes, it 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.
Click on the View Node Shapeicon. This will show all Node Shapes in the panel below the Class Hierarchy. Click on the New button.
Editing Classes, Properties and Shapes
When an item is selected in the hierarchy (class or property), its details appear in a form 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 form has a button bar providing access to available actions. These options are described in the table below.
|Element Name||Displayed As||Description|
|Actions for <class> Menu|
This menu lets you:
|Visualization actions for <class> Menu||This menu lest you select any graphical views (e.g., NeighborGram, etc.) that are pertinent to the selected item.|
|Open in new browser tab||Opens a new browser-tab with the full-width form displaying the currently selected item. When a form is displayed full-width, you will have access to the Source Code panel - unless it was disabled for your system or your role.|
|Edit / Save Changes, Cancel Buttons||(button)||These buttons toggle the details center pane between view and edit modes. Edit will open the form for editing showing all available properties. Save Changes ad Cancel switch back from the edit to view mode.|
|Delete Button||(button)||After confirmation, this deletes the selected resource. It will also delete some associated items. For example, deleting a class will delete all its instances if they are present in the ontology. Deleting a property will delete all property shapes that use it as path.|
|Print Button||(button)||Creates a page for printing the resource's view.|
|Start Workflow Button||(button)||Let you start a new workflow for the selected resource.|
Lets you view already created tasks for the selected resource and enter a new task. (see also: $ModelType Utilities > Tasks View).
Note: this only appears if an administrator has activated the feature (see Administration: $ProductAbbrevName Configuration Parameters).
Lets you view already created comments for the selected resource and enter a new one (see also: $ModelType Utilities > Comments View).
Note: this only appears if an administrator has activated the feature (see Administration: $ProductAbbrevName Configuration Parameters).
|Show Problems & Suggestions||This toggles on/off the dynamic checking of validity of the resource information anytime it is displayed on the form. Note that activating this option might impact performance.|
|Show History||(check-box)||Displays the history of changes made to the resource, and it lets you revert particular change steps.|
Like with classes, detailed view of selected properties shows up on a form in the center pane. The property form display will have at least two sections and it may have as many as 3 sections: Labels and Descriptions, Global Property Characteristics and Local Property Characteristics.
click images to enlarge
What sections are shown when the Edit button is clicked depends on the whether Prefer SHACL over OWL/RDFS option under the Manage tab is checked or unchecked. By default, it will be checked.
When it is checked, clicking on the Edit button lets users edit not only information about a property but also about shape(s) it participates in - as shown below. Global Property Characteristics section will only be shown if some of the fields that are normally displayed in this section have already been populated. This could happen, for example, if you have been switching between prefer and not-prefer SHACL modes. The screenshots are showing such examples. Typically, if you are working with SHACL, you should not be setting up domains and ranges.
Sections: Labels and Descriptions, Global Property Characteristics contain information about the property itself. Section Local Property Characteristics contains information about the shapes. The information you will see and be able to edit in this section is the same as the information you will be able to see and edit if you navigate directly to a property shape and click Edit.
When Prefer SHACL over OWL/RDFS is unchecked, Local Property Characteristics section will appear only if a property you are editing is already used in one of the shapes. Otherwise, it will not be shown - as demonstrated below.
Setting a primary key for a class
To use a class as the main entity of any reference dataset (see Create New 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. The primary key constraint guarantees that each value of the property is unique across all instances of the class.
To set a primary key constraint, edit the chosen property. Under Local Property Characteristics > Primary Key > URI start, enter the prefix of the URI pattern that will be used to construct the property values (i.e., the individual URIs, with unique suffixes). Click Save Changes. After refreshing the Class Hierarchy pane, it will show the selected property with the primary key icon, for example:
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:
Working with Wikidata or other external Knowledge Graphs
Sometimes it is useful to link your data with entities from external knowledge graphs. An example of how to define ontology support for such linking is explained in details in the following tutorial.
Derive View Shape wizard
EDG lets you create different views into assets.
After selecting a Node shape or a class (that is also a Node shape), the gear menuitem "Derive view shape" opens a dialog that can be used to let the system generate a new SHACL Node shape similar to the currently selected class.
Example use case: Assume you have selected Country in the geo ontology and want to create a new "view" shape that only contains a sub-set of the available properties of Country. In the Derive view shape dialog, enter a name such as "Simple Country Shape" and select only three properties - preferred label, alternative label and broader relationship.
On pressing OK, the newly created node shape will be selected and can be edited further. For example, properties that are associated with the shape can be moved to different groups. When a class has multiple node shapes that are "targeting" class members, users viewing or entering information about assets will be able to switch between different views. A view that EDG will automatically select for presenting an asset when multiple alternative views are available is called the "default view". User will be able to switch from the default view to other available views.
If no further set up is performed, the default view for every user will be the one that is defined directly for the class.
Optionally, the alternative view shapes such as Simple Country Shape can be assigned to be the default view for selected user roles, e.g. all data stewards. This is defined in a node shape by using the default view for role property in the Targets and Applicability section.
Cloning a Class or Property
You can clone (copy) any existing class or property or shape, 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.
Use of Names and Descriptions
When you create classes and properties, it is recommended to enter their descriptions in the comments field that is available on the form.
This is important for documenting the intention and purpose of your model elements. The description will show in the pre-view panel of resources that reference a class or a property, thereby, minimizing click-throughs needed to understand your model.
For properties, their descriptions will be displayed on the forms for editing instances - either on the mouse over or on the form itself, if user clicks on the i icon.
Shapes have their own fields for entering names and descriptions, called name and description. Name field is used to override the label of associated property. For example, if you have a property with a label has broader, you can override it so that its display name is broader concept. Description field overrides the comment associated with the property. In other words, you can use it to give a contextual description to the property and, when exists, if will be displayed instead of the comment entered for the property.
Deleting Classes, Properties and Shapes
To delete a class, property or shape select it in the hierarchy or navigate to it in some other way to get it displayed on the form and then select Delete... button on top of the form.
Deleting a resource will also delete some associated resources that are defined in the ontology.
Keep in mind that if you have class instances in another asset collection, deleting a class will not remove them. It will make them members of undefined class. Similary, deleting a property does not delete property values that are held in another asset collection.
Changing a Class's Parent
In the Class Hierarchy, you can change a class's parent in order to refactor the class hierarchy.
Subclass relationship can be modified on the class form. Select a class in the Class Hierarchy, Edit it, and in the Class Characteristics section, 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 which will be represented with a lighter color circle on the Class Hierarchy.
Adding Constraints to a Class
NOTE: Constraints in TopBraid $ProductAbbrevName have moved to the W3C recommendation: Shapes Constraint Language (SHACL) . Users are encouraged to consult this tutorial on using SHACL in an ontology. For background, also see this ).
You can specify constraints directly on the class to, for example, constrain URIs of its members. To do so, select a class, click on Edit and make desired modifications. In general, it is fairly uncommon to declare constraints directly for a class.
Or you can specify constraints for property values that members of the class can have. These constraints are specified within property shapes that associate a property with a class. If your ontology is in the Prefer SHACL mode, creating a property, as explained above, will automatically create a property shape. To associate already existing property with the class or to create a property shape for a property that is not directly connected to the class, select the desired class in the hierarchy view and then click Add Property Shape...
To access existing shape, either (a) select the desired class in the hierarchy view, then click on the property shape you want to edit (displayed as a rectangle in the class's detail view) and then click Edit; or (b) select the desired property in the hierarchy view, click Edit. Most constraints can be created and modified directly on the property form, but some (like deactivation) require navigating to the shape.
Constraints that get checked by the data validation are called "validating". These include min/max count, datatype, class and nearly all other constraints
Non Validating Constraints
A small subset of constraints do not get checked by the data validation are called "validating". These include group, order, etc. They are used to support user interfaces e.g., display fields on a form in the right order.
Majority of these constraints are grouped under Display Settings section.
Working with Groups and Arranging Properties into Groups
When specifying non validating constraints, you can select an existing Group for a property or use Create new... in the drop-down menu to the right of the group field value to create a new group.
Groups will be displayed as sections or, optionally, tabs on the forms for class instances. You may also want to specify order of a property in a group. A convenient way to preview how sections and properties will look like on the form is available if you click on a class and select View/Edit property layout groups...
If none of the property shapes associated with the class have any group assignments, you will see a message that there are no property groups. However, if you specified a group for at least one of the properties, you will see a floating dialog displaying groups and properties - as shown below:
If group or property order has not been specified, you will see a question mark and items will be ordered alphabetically. Otherwise, you will see the order number and items will be order according to it. The dialog serves as a navigator. If you click on any of the displayed items, its information will be shown in the form. When no order exists you can also enter it directly in the dialog by clicking on any of the items without the order information. Order can be any number, it does not have to be an integer. So, if you, for example, already have a property with order = 1 and a property with order = 2 and want to put a new field between them, you could use 1.5 as the order.
SPIN Constraints (deprecated)
$ProductAbbrevName no longer lets you add new SPIN constraints to classes. If attempted, it will show message indication about using SHACL.
You can not deactivate just one constraint, but you can deactivate the entire shape. Typically, this is done for property shapes to "remove" properties you do not need.
Click on the property shape you want to edit (displayed as a rectangle in the class's detail view or in the property detailed view), then click Edit. Select "true" in the deactivated dropdown.
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.
Defining Dynamically Inferred Property Values
EDG lets you define properties values of which will be automatically inferred from the values of other properties. Inferred values will be shown in the UI as un-editable fields. They can also be queried for in GraphQL and SPARQL.
Example: We want to show for airports, the numeric country code of the country they are located in. We will create a new property for airports and auto-populated them with values from related countries.
Create a property for a value that is to be dynamically inferred. For example, in the screenshot below we are calling it "numeric country code".
Navigate to the property shape and select from the gear menu, Create property value rule from template ...
Select one of templates. We will choose to copy indirect values.
Depending on the chosen template, you will be asked to enter additional parameters. In our example, we are selecting a relationship between airports and their countries and then the property to holds numeric code for countries.
Complete the entry and click finish.
Your rule will show up in the Inferences section and can be further edited.
Alternatively, you can enter expression directly in the values property - without using the wizard which only supports a few common patterns. For example, if you wanted to show official currency used at the airport, you would need to go from Country to Currency which is two hops away. Wizard does not support it, but you could enter this expression into sh:values. For more details and examples, see this page.
Defining Default Values for Properties
EDG lets you set a default value for a property. The default value will be editable by users and will only exist if there are no other values for the property.
Default value is set in the Type of Values section of the property shape, using default value field. It can be a static value or a rule like the rules that are specified for the values property - as shown above.
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. These entry fields are only available if Prefer SHACL over OWL/RDFS option under the Manage tab is unchecked. 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 UML-like 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 visualization buttonand select the Display NeighborGramTM... item. The views opens in a new browser tab.
When a resource node has over 10 different relationships, they will be shown in 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 or a node shape, the form shows a Class Diagram section which contains several subsection links with the diagram options. Selecting a subsection link opens a nested form showing the resources associations in a UML-like diagram.
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: No-Instances Mode
Search options available in the Search pane of the ontology editor application depend on the chosen mode. When the ontology is in the No-Instances Mode, you will see a search form that 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, property search and shape search.
Also see Template Queries for URI-based searches.
Basic Search Form
The basic search form provides several options in how you search and what you can do with your search results. The search form has a field for each property you can search on. One can use a combination of fields to specify search criteria. The Search any Text field matches on any property that is configured to be included in a free text search (See the Configuring Search Text Properties section in the Developer Guide for how to add this field to the search form and configure which properties it should search).
You can switch between searches for classes, properties and shapes by clicking on the corresponding icon in the upper right of the search form.
Selecting Return local results only will deliver only classes, properties or shapes (depending on your selection) 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.
The screenshot below shows what properties you can use to search for classes.
For each property, you can specify the type of match. Different properties can use different match types, all combining together to produce an overall search result. These options are selected by clicking on the triangle to the right of each field which displays a menu with options.
|Type of Match||How a search value matches instance property-values|
Text DEFAULT: Search text is a substring of a property- value (case-insensitive). Example: Search text "sta" on a label property would match resources having label values such as "State", "Status", and "Postal Code".
|text equals||Search text is exactly the same as a property- value (case-sensitive)|
|text matches regular expression||Search text is a regular expression that matches a property-value (case-insensitive). Example: Search text "^sta" as a regular expression matches label values that begin with "sta", e.g., "State", "Status", but not "Postal Code". Conversely, "sta$" would match only at the label's end.|
|any value||At least one value exists for the search property (count >= 1). Example: See how extensively a property is used.|
|min/max number of values||The number (count) of property-values (occurrences) is within the search range, inclusive. Example: If most classes in the ontology have labels in three languages, entering a label search with values-range 0 to 2 would return those with fewer.|
|no value||No values exist for the search property (count = 0). Example: Use to clean up ontology and check for remaining work.|
|boolean||Boolean DEFAULT: Search values restricted to true/false instead of free-text|
|equals||Relationship DEFAULT: Quick-search field for specifying other resources as search criteria. Example: Used with sub-property of to find properties that are sub-properties of the selected property.|
|nested form||Adds an embedded search form for properties whose type is another class|
|label matches regular expression||Search 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. 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, $ProductAbbrevName 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 resource 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|
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 buttonat the bottom of the Search form. This preserves the current settings as the new default for all users.
Search Results Operations
The gear menubelow 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.
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.
Show SHACL query shapes... displays a pop-up window with the SHACL query that is being generated on the server when the search form is executed.
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 $ProductAbbrevName 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 subclasses of Geo Concept, 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.
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 $ProductAbbrevName, the saved search servlet lets other applications execute saved searches by using the appropriate URL. The "Save current search" buttondisplays 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 $ProductAbbrevName. 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.
Searching within an Ontology: Instances Mode
When the ontology allows instances, search pane will let you search for instances of a class you select in the Class Hierarchy using the Search View. Please note that there are minor differences in the layout and all options may not be available depending on the collection type and class type you are viewing.
Note: Full instances search capabilities described in this section are only available if your properties are described using SHACL property shapes. Otherwise, you will only be able to use full text search. For information on how to create SHACL from RDFS/OWL statements, see SHACL Enablement.
Searching and Browsing in $ModelTypes
The Search panel lists assets of the selected type in a sortable table. From here, users can further filter displayed assets, export information and perform other operations. The main features available in this panel are:
- Searching for assets and displaying them in different ways.
- Viewing and editing asset information.
- Performing various actions on assets, either individually or in selected groups.
Controlling Asset Type
You can control what is displayed in the table by using Type Selector described below. This option is not available for ontologies where the type is selected by clicking on one of the classes in the Class Hierarchy.
|Element Name||Displayed As||Description|
Lets you to select type(s) of assets to show in the table. You can select an asset type either from the Type drop-down list (it supports autocomplete so you a start typing the name of an asset type you are interested in) or you could click on the button next to the drop-down list, which opens a browsable hierarchical navigator listing available asset types.
Searching for Assets
You can search among the assets of selected type by using the various options available in the light gray upper box. These include:
- finding assets using free text (any property),
- finding assets by filtering on specific property values, and
- using advanced search queries.
These options are explained in the table below:
|Element Name||Displayed As||Description|
|Free Text Search Box||Lets you type in a search criteria that will be matched against values in any properties of selected type of asset that contain text.|
|Advanced search Link||Advanced||The Advanced link opens a GraphQL query box. For a tutorial on GraphQL in EDG please go to the Export tab of a collection > GraphQL Queries > GraphQL in TopBraid Tutorial. For more information please go to https://graphql.org/.|
Clicking on Filters displays a drop-down lists of properties defined for the currently selected asset type and lets you select and deselect them. When a property is selected, a search widget will appear where you can enter a search criteria that is applied to deliver a subset of results. Each property filter supports various kinds of matching types described in a table below. Users can select multiple properties and specify search criteria for each. Clicking the search button will load only assets whose properties match the specified filters (along with any other selection settings).
|Columns Button||Clicking on Columns displays a drop-down lists of properties defined for the currently selected asset type and lets you select and deselect them. When a property is selected, it will be added as a table column.|
|Search Button||Runs a query based on the specified search criteria and presents results in the table.|
|Reset Active Filters||Removes all currently specified search criteria, including any defaults (which remain saved).|
|More Search Options Menu||This menu lets you perform operations on the results of the current search. You can select to batch edit all resource returned by your current search or export them in a choice of formats. It also provides an option to view GraphQL generated for the current search query, open a dialog that will let you name and save the current search criteria (query) for later use and open a list of any previously saved queries for this collections. User with manager privileges will also have an options to save the current query (including any search criteria and selected columns) as the default one for all users. The default will automatically be displayed to everyone who navigates to the collection and selects the asset type for which there is a default search.|
|Return Local Results Only Checkbox||When checked will ensure that the search query is ran only against assets directly defined in the current asset collection. In other words, will exclude from results any assets defined in the included collections.|
By default, you will see only 1000 rows of search results. (To change this maximum number of asset results: see Administration > Server Configuration: SWP Parameters > maximum number of table rows.)
For each property selected using Filters drop down, you can enter a search criteria and specify the type of match. This determines how EDG uses the value you enter in that field to search for matching data. Different properties can use different match types, all combining together to produce an overall search result.
Type of Match
How a search value matches instance property-values
DEFAULT for text properties: Finds resources that contain the entered search string (case-insensitive) in the property value. Example: Search text "lis" on a city-name property would match instances having city-name values such as "Lisbon", "Lisboa", and "Minneapolis".
|equals||DEFAULT for relationships: For attributes, this will match the entered string exactly to the property value (case-sensitive). For relationships, this becomes an auto-complete field for selecting a related asset. 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 resources that begin with the typed letters.|
|regular expression||For text properties, searches text using 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. For relationships, does similar matching, but on the labels of related resources.|
|any value||At least one value exists for the selected property (count >= 1). Example: See how extensively a property is used.|
|min/max number of values||Finds resources whose number of values for selected property fall in the range specified by the one or two numbers you enter. Example: If most resources in a $ModelType have labels in three languages, entering a label search with values-range 0 to 2 would return those instances with fewer. Leaving min range empty and just using 2 in the max field will return the same results.|
|no value||No values exist for the search property (count = 0). Example: Use to clean up a $ModelType and check for remaining work.|
|boolean||DEFAULT for Boolean properties: Search values restricted to true/false instead of free-text|
|nested form||Available only for relationships: Adds an embedded search form for properties whose type is another class|
|min/max (inclusive)||DEFAULT for numeric properties: Finds resources that are within the range of entered search criteria, inclusively.|
|min/max (exclusive)||Finds resources that are within the range of entered search criteria, exclusively.|
Switching between Tabular and Hierarchical Displays
You can also switch between the tabular and hierarchical views. This option is explained below. It is not available for ontologies.
|Element Name||Displayed As||Description|
|Switch to Properties Hierarchy View Button|
This button replaces the table with a two-column view that displays assets hierarchically in the left column and the details of a selected asset in the right column. The hierarchy will be structured according to a user selected property relationship (e.g., "has broader") or its inverse. This option is available in the light grey upper box.
|Switch to Table View Button||This button is displayed after you switch to the hierarchy view. It will let you revert back to the tabular view.|
Actions on Search Results
These options are selectable either from the rows of page elements just above the table of search results or within the table itself and, finally, in the footer below the table.
Note: Not all options are available for all types of Collections. For example, edit features such as New and Delete, are not available when the Search View is in display-only mode such as in Ontology asset collections.
|Element Name||Displayed As||Description|
|Refine Text Box||The Refine text field is similar to the free text search (above) except that it only affects the visibility of the loaded assets, without affecting which assets are loaded into results table, i.e., the underlying search scope is unchanged, refines operates on the data in the table. Refine matches the string will against data in any of the table's columns.|
|Clicking on this button lets you create a new asset of a chosen type. The Create Dialog will let you select a sub-type, if any are available.|
|This button is clickable only when a single asset is selected. It displays information about the selected asset in a form in a new browser tab .|
|Delete||This will let you delete all of the currently selected assets.|
|Clone||This button is clickable only when a single asset is selected. It creates a copy of the currently selected asset.|
|Export||This menu lets you export the selected rows in a choice of spreadsheet formats and, if a single asset is selected, lets you print out its detailed information.|
|Resource Actions Menu||This menu is clickable only when a single asset is selected. It lets you add it to the basket and runs and displays a report that identifies any active workflows that may impact the selected resource.|
|Visualizations Actions Menu||This menu is clickable only when a single asset is selected. It lets you select amongst the various graphical diagrams for assets (e.g., NeighborGram, etc.). Availability of some diagrams depends upon the type of asset to be viewed.|
More Actions Menu
|This menu is clickable only when a single asset is selected. It lets you add tasks or comments to a selected resource, add it to the basket or start a workflow for it.|
|Show Number of Entries Drop-down||By default, table displays 25 rows, but you can select a different number of rows|
|Table Header Row||This is the first row of the table. It displays names of currently selected properties. You can sort the table in the descending or ascending order by clicking on one of the columns. You can also re-arrange the order of the columns in the table by dragging and dropping columns in the first row.|
|Checkbox Column||The first column in the table contains checkboxes. These get checked when you click on a row to select it. You can select multiple rows. In addition to the checked checkbox, another indication that a row is selected is that its background color changes from white to blue. To deselect, click again.|
|Pencil Icon||This icon shows up when you mouse over any cell in the table except for cells in the first, header row or the first two columns. When clicked it opens the values in the cell for editing.|
|Save Icon||Lets you save edits made in a cell of the table. You must click on either Save or Cancel icon to exit the cell editing mode.|
|Cancel Icon||Exits the cell editing mode without saving any changes.|
|Counter||Counter is shown at the bottom of the table. It shows the total number of assets displayed in the table and the number and sequential order of assets displayed on the current page. The maximum number of assets to display in the table is set in the Server Administration console. When search results exceed the maximum, TopBraid EDG will display a message at the bottom of the table.|
|Previous Button||Previous||This button is shown at the bottom of the table. It lets you page through results.|
|Next Button||Next||This button is shown at the bottom of the table. It lets you page through results.|
Template Queries (Find by URI)
In the ontology editor header, the Execute template querybutton pops up a dialog for searching by resource URI, matching by full-string (fastest), partial, or regular expression. On execution of a query, the dialog's result table lists matching resource URIs, and double-clicking an item loads the resource into the form pane.
Find by URI is available in both, No-Instances and Instances modes.
Working with Instances
If your ontology contains instances, you can select them from either a table view below the class hierarchy or from the search results table. Once selected, they are displayed in the form in the center panel.
A form displays the following menu, explained in the table below:
|Element Name||Displayed As||Description|
|Resource Actions Menu||This menu lets you add resource to the basket, clone it and run and display a report that identifies any active workflows that may impact the selected resource.|
|Visualizations Actions Menu||This menu lets you select amongst the various graphical diagrams for assets (e.g., NeighborGram, etc.). Availability of some diagrams depends upon the type of resource to be viewed.|
Open in a new browser tab
|Displays information about the selected asset in a full width form in a new browser tab. When the form is open full width, you may have access to a collapsable source code panel. It presents serialized information about selected resource in one of standard serialization of RDF - Turtle. Access to this panel is configured by your EDG administrator.|
Edit button switches form into the editable mode, making all property values editable. Alternatively you can also edit any of the displayed values by mousing over to the left of the value and clicking on the pencil icon. When in the editable mode, Edit button is replaced by Save and Cancel buttons. You will also be able to log a message with the saved changes. The log message is saved with the history of the change and can be seen from the change history report as a comment and also at the inline change when selecting show history in the form.
Note: If you navigate away without saving, your changes will be lost.
|[button]||After confirmation, will let you delete currently selected resource.|
|[button]||Creates a page for printing the resource's view.|
Start Workflow Button
|[button]||This button lets you start a workflow for the selected resource.|
Lets you view already created tasks for the selected resource and enter a new task. (see also: Ontology Utilities > Tasks View).
Note: this only appears if an administrator has activated the feature (see Administration: EDG Configuration Parameters).
Lets you view already created comments for the selected resource and enter a new one (see also: Ontology Utilities > Comments View).
Note: this only appears if an administrator has activated the feature (see Administration: EDG Configuration Parameters).
|Show problems and suggestions Toggle Button||When toggled on, EDG will run validation for a resource every time it is displayed on the form. If any issues are found, the number of issues will be shown next to the button. When toggled off, validation will run only on data save.|
Show History Checkbox
|When checked, the form will display the history of changes made to the resource and let you revert particular change steps.|
When you are editing data, + icon next to each field will display another empty slot to let you enter multiple values for a given property. If it is not available, the property is defined as having a single value.
When entering a value for an attribute you typically simply type the value. Depending on the datatype, you may also have a widget (such as calendar) to select the value.
When entering a value for a relationship, you have the following options:
- Start typing the name of the related resource and pick it from the auto-complete list
- Use Select using search dialog ... This is useful if you are not sure what laters the related resource's name starts with. As shown below, clicking on this option opens the search panel where you can use all the search functionality to find a resource you want to connect to.
- Use Create new ... This will open the Create dialog. It will create a new resource and connect to it.
Working with EDG Models
To modify any ontology models pre-packaged with EDG, create a new ontology, include the model you want to modify.
Then, add new classes, properties, shapes and/or deactivate shapes as needed. For a worked example see Getting Started with Business Glossaries tutorial.