Skip to end of metadata
Go to start of metadata

Page Contents



The TopBraid EDG Vocabulary Management package works with taxonomies, ontologies, and crosswalks. With the Tagger and AutoClassifier add-on module, one can also work with corpora (document collections that reside in a content management systems) and content tag sets (data-sets that tag documents using terms defined in your vocabularies).

A taxonomy is a vocabulary collection based on SKOS, the W3C standard ontology designed for managing taxonomies, thesauruses, and other controlled vocabularies with associated metadata. For the TopBraid EDG - Vocabulary Management package, this guide shows you how to edit a taxonomy, manage a set of edits, and review the history of changes. It also provides information on how to create and modify ontologies.

The taxonomy editor offers SKOS-based features, such as displaying a SKOS model's Concept Hierarchy (where concepts are connected by SKOS broader statements) starting with the defined Concept Schemes as hierarchy roots. Every taxonomy must have at least one concept scheme that identifies "top concepts" in a scheme. Although a taxonomy can have multiple concept schemes, a recommended practice is to use a single scheme per taxonomy. Like all asset collections, taxonomies can be included into other collections, which means that a taxonomy with multiple concept schemes can be assembled through the inclusion of several single-scheme taxonomies.

The set of predefined SKOS fields that a taxonomy uses can be customized for existing individual or subsets of taxonomies, or for all new taxonomies created in EDG. To simply add/remove (enable/disable) some of the fields for a given taxonomy, go to its Reports > Problems and Suggestions > View Shapes and Constraints view and select/deselect the fields. To apply common settings to sets of taxonomies (e.g., ones associated with a business area) define one or more ontologies with the common settings and then include them into the applicable taxonomies. Ontologies also support defining custom extensions to taxonomy concepts, including adding non-SKOS properties and specialized subclasses. To have such special inclusions apply automatically to all taxonomies created in EDG, an administrator can set them via Server Administration > EDG Configuration Parameters > Configure Collections .

Accessing the EDG Application

To work through this guide, use a browser to access the EDG web-application running in one of the following environments.

  1. Create an EDG trial evaluation at TopQuadrant, and run EDG from the TopQuadrant servers. Submit an EDG evaluation request or contact TopQuadrant.

  2. Use TopBraid Composer - Maestro Edition (TBC-ME), and run its demonstration version of EDG. Download and install TBC-ME.

  3. Install EDG on a server accessible to your network (which could also be a local Tomcat server, via localhost). For a custom install, contact TopQuadrant and see EDG Server Installation and Integration. This will also require separate uploading of the EDG samples project:, from TBC-ME.

For the TBC-ME option, launch TBC-ME and then start the demo version of EDG via the top menu: TopBraid Applications > Open TopBraid EDG. Browse to  http://localhost:8083/edgLogging in as Administrator requires no password for the demo version. All asset collection types are available in the demo version.

For the other two options, the system administrator or TopQuadrant will provide you with a URL, a username, and a password. Browse to the URL and log in. Server licensing will determine the availability of the various asset collection types.

The EDG User Interface

For a basic orientation to the user interface, see EDG User Guide - Overview.

Vocabulary Management with Taxonomies

Selecting a Taxonomy

After logging in, the application's main screen will appear. On the right of the banner at the top is a link that lets you log out, and below that is a Help link that leads to the EDG documentation.

If the Taxonomies tab is not selected, go ahead and select it. It shows the list of taxonomies available to the logged-in user and some metadata about each one.

This tutorial uses the Geography Vocabulary that is included with TopBraid Composer (Maestro edition, TBC-ME) and EDG evaluation-servers. If your server does not have it, an EDG administrator can upload it from TBC-ME. For information on creating a new taxonomy, see Create New Taxonomy.

Metadata about each asset collection includes the user name of the person who created it, the date and time of its creation, the number of workflows in progress for that asset collection, as well as information about users who have been assigned viewereditor, or manager permission roles for that asset collection and users' governance roles, if any. If the system administrator has given you access to the Geography vocabulary, or if you are logged in to a TopBraid Composer demo version of EDG as the Administrator, EDG will display its title as a hypertext link. Click that link to go to the management screen for that asset collection.

If you do not see a collection that is known to exist in your system, you might not have the appropriate viewing or editing privileges for it. To gain access, a manager for that vocabulary must assign you a viewer (or higher) role. For details, see Taxonomy Utilities > User Roles.

The Utilities View

The taxonomy's (main) utilities view lets one perform various operations on the asset collection (e.g., import/export, etc.). See Taxonomy Utilities for details on these features. The Edit Production Copy link near the top lets one see and modify content in the collection, i.e,. concepts in the taxonomy. Any changes made will apply immediately when saved. Instead of editing the taxonomy's production copy directly, we will create a workflow, which will isolate a set of changes we will be making, keeping them in a working copy until the workflow completes and changes are committed to the production copy.



The production copy is the version of the vocabulary currently in use. For example, an online store that organizes menus of product categories based on a managed vocabulary would use the production vocabulary when it builds the menus used on their website. In this case, the production copy is a Geography Vocabulary.

working copy is a virtual copy of the production vocabulary created for editing purposes. When you start a workflow, an associated working copy is created to hold the changes that will go through the workflow process and, eventually, may get committed to the production version at the discretion of the users who have permission to make and execute such decisions.

It is possible that several “in progress” workflows, each with its own set of working copy changes, exist at the same time. These workflows are shown in Workflows tab. Out of the box, EDG has a built-in review and approval workflow called “Basic”. Users can create their own custom workflow templates. More information is available in the Workflow Overview section.

When you edit the production copy and save your edits, those changes will be visible by everyone using the production copy. They will also show up in any working copies created for this production vocabulary. When you edit a working copy, changes will only be visible in that working copy.   EDG users with the appropriate permissions can choose between making changes directly to the production vocabularies and using the workflows and associated working copies to change, review and publish new versions.

TopBraid EDG comes with the prebuilt Basic workflow template. Users can define custom workflow templates to support an organization's own vocabulary management processes. Working copies managed by the Basic workflow can be in the following stages aligned with the states of the workflow:

  • Uncommitted working copies are copies of the production vocabulary that people are currently making changes to. Changes are not reflected in the production vocabulary until the workflow completes successfully and changes are committed, or published, to the production copy. Uncommitted working copy can be frozen for review or it can be directly committed to production without a review step by users with appropriate permissions.
  • Frozen for review working copies are working copies that are going through a review. No one has permission to modify them. This is useful to allow people to review changes while knowing that no further edits can be made during the review period. Users can enter their review comments. Frozen for review working copy can be rejected, approved or simply unfrozen to allow further changes to be made. The latter choice returns its state to Uncommitted.
  • Rejected working copies are working copies that cannot be edited or published. A rejected working copy can be opened for further changes, changing its state back to Uncommitted. Another option at this point is to cancel the workflow. When a workflow is cancelled, all changes in a working copy are permanently deleted.
  • Approved working copies are working copies that have been approved but that have not been committed yet. No one has permission to edit them and the only possible next step is to commit them. This is useful as a final review stage late in the editing workflow to explicitly record that the approval was granted and by whom.



On the vocabulary's User Roles tab you can see a list of users and their roles. EDG supports permission roles and governance roles. There are three pre-set permission roles. Governance roles are open to customization.

A user can have one of the following permission roles for a production copy:

  • Viewer can browse a production copy, viewing the concepts and their metadata as well as any change history associated with that data. A viewer can also generate reports about the vocabulary, export it in other formats, and start workflows for the vocabulary. The viewer then becomes the new working copy's manager.
  • Editor has all viewer permissions and can make changes to its content. Since an editor can make changes to the production copy, she has sufficient permissions to commit to it changes made by any workflow. The basic workflow allows an editor to approve changes in working copies governed by the basic workflow.
  • Manager has the most capabilities. In addition to all editor permissions, a manager can control the access privileges that other users have for a vocabulary by assigning manager, editor, or viewer permissions to them. Manager can also perform all actions in the Manage tab - including ability to delete a vocabulary. A user that creates a vocabulary automatically gets  manager permissions for it.

A user can have one of the following permission roles for a working copy of a vocabulary:

  • A Working Copy Viewer can do the same things with a working copy that a production copy viewer can do with a production vocabulary: view its data, view its change history, generate reports, and export the data.
  • A Working Copy Editor has working copy viewer permissions and can also edit a working copy.
  • A Working Copy Manager has working copy editor permissions and controls the working copy's access roles assigned to other users. A user that starts a workflow automatically gets manager permissions for the associated working copy. The basic workflow allows a working copy manager to freeze a working copy for review and revert a frozen copy back to uncommitted status so that those with the appropriate permissions can continue to edit it. The basic workflow also allows a working copy manager to reject working copy's set of changes.

On the Workflows tab, click the Start new Workflow link to create your first working copy. On the Start new Workflow on Geography Vocabulary screen, enter "South Korea Updates" as the workflow's name. In the Description window enter "Fix country name and add Busan". Click the Submit button. After creating the new workflow EDG will send you to the newly created workflow's management screen, where in the Workflow tab you'll see the current status of the workflow and the next steps that can be undertaken.

If you go back to the Geography Vocabulary > Workflows tab, you'll see that your South Korea Updates Workflow will have the state Uncommited:


In order to make changes to "South Korea Updates" click on a row in a table (it will highlight to blue) and in the top right menu click on Go to Working Copy button. If instead of editor, you want to go to management screen for "South Korea Updates", click on Go to Workflow instead.

Editing A Working Copy

When you are logged in as Administrator, you are the asset collection manager for the Geography vocabulary, so you have the highest level of permissions. Users assigned less powerful roles for the Geography production vocabulary will not see as many choices available. For example, someone in a viewer role would not see the Edit Working Copy link at the top, but instead would see View Working Copy link:



For the purposes of this guide, we assume that you are the Administrator or have a similar level of permissions and you have just started the South Korea Updates workflow.

To make changes, click the Edit Working Copy link, and you'll see the editing screen that has three panels: a taxonomy tree, a form that will show a concep tyou select and a search panel that lets you find concepts from detailed search criteria.

You can drag the dividers between the panels to resize theml The side panels can be collapsed to make more room. If your search pane is displayed, collapse it now by clicking the dark part of the divider (pointed to by the arrow) between the center pane and the search pane:



This leaves plenty of room to display data about the vocabulary's concepts. (We'll come back to searching later.)

In the Concept Hierarchy tree, clicking the little arrows will expand and close up sub-trees of concepts. Note that SKOS organizes concepts into concept schemes. So, the root of the tree will always be a concept scheme. It is differentiated by the blue icon while concepts have manila folder icons.

Click directly on a concept's name to see data about it in the panel on the right. For example, click on the arrow next to "Europe", and then click on "Belarus", and you will see information about this term on the right of your screen. This includes information that is part of the W3C SKOS standard for vocabulary management, such as an alternative label for the concept and a history note about it. It also includes custom properties added to extend the SKOS standard for this vocabulary, such as the area figure for the country and their calling code.


Alternative label and history note are both attribute properties. Relationship properties such as Belaurus's "has broader" and "has related" values describe relationships to other concepts, which may or may not be in the same vocabulary. Relationship properties are hypertext links; double-click Belaurus's "has related" value of "Soviet Union" and the same panel will display data about that concept. (Use your browser's Back button to return to the Belarus screen.)

In addition to the Concept Hierarchy, another way to find specific concepts is to use the quicksearch

To quickly locate specific concepts in the tree use the lookup field in the upper-left of your screen, under the Concept Hierarchy heading. Type the word "South" there, and a list will show you the concepts beginning with these letters.


Select "South Korea" from the list, and EDG will take you to that concept on the Concept Hierarchy and on the main panel. We're going to change its preferred label value to the country's official name of Republic of Korea and make South Korea the alternative label, and then we'll add the city of Busan as a new concept that appears as a child node of Republic of Korea in the Concept Hierarchy.

Even if you have the appropriate rights to edit a given vocabulary, if that vocabulary includes data from other sources, you will not be able to edit or delete the included data. See Included-By and Includes in the User guide for more information.

Once you have the South Korea data displayed, click the Edit button at the top of the screen to display the edit screen for this concept:


Before you clicked the Edit button, the form only displayed the concept properties that had values assigned to them, but the edit screen displays all possible properties for the concept that you are editing so that you can add new ones. There is the scroll bar on the right of the editing screen above (hidden or not, depending on the browser) - there are enough potential properties for this concept that they won't all fit on one screen.

Replace the preferred label value of "South Korea" with "Republic of Korea".

By default, one can add multiple values for a single property unless its underlying ontology explicitly limits the property's number of values (its cardinality). We're going to add the Spanish term for "South Korea" to this concept. Click the plus sign next to preferred label and a new blank appears under "South Korea". Enter "Corea del Sur" there, and pick "es" from the drop-down list to the right of it. (Your EDG administrator can customise the list of language code choices offered on this list.)


EDG has a built-in set of rules to implement constraints defined as part of the SKOS standard, such as the rule that says that you shouldn't have two different preferred labels for the same concept in the same language. (Your EDG administrator can customize these rules for each vocabulary and add new ones depending on your vocabulary management requirements).

Another SKOS rule says that you can't have an alternative label that is the same as the preferred label in a given language. Let's break this rule and see what happens. Enter "Republic of Korea" as the alternative label for this concept, with a language code of "en", and click the Save Changes button at the top of the screen. A message box will tell you about the problem, and the label for the property with the problem is displayed in red behind the message box:


Click this message box's Cancel button, set the alternative label to "South Korea", and click the Save Changes button again. You'll be returned to the concept display screen, where you'll see your new values; also note that the node of the Concept Hierarchy tree on the left that had been labeled "South Korea" is now called "Republic of Korea".

Next, we're going to add a new concept. First, click the arrow next to your "Republic of Korea" node to see its children. It only has one: the city of Seoul. To add a new child node, make sure that "Republic of Korea" is selected on the tree and click the "Create Concept" button  at the top of the Concept Hierarchy pane. EDG will display a Create Concept message box to ask you for some information about the new concept:

  • The Label is the preferred label for the new concept. Enter "Busan" here. As we saw when we edited the "South Korea" preferred label, we can always change a label later.

  • The Identifier is the internal ID used by EDG to track the concept. (Because SKOS is based on the W3C RDF standard, this ID is a URI.) Advanced users sometimes have reasons to customize this, but you can't go wrong by just leaving the default value that appears.

  • The Type identifies whether the new Concept is a regular concept or a specialized class. EDG lets you create these classes so that specialized properties can be stored for some concepts but not others—for example, so that forms for editing or searching countries include the calling code, but forms for editing and searching continents do not. Leaving this set at the default value of "Concept" is usually fine, but because you're adding a city and a City type has been included with the Geography vocabulary, pick that and click the OK button.

EDG will add Busan as a new child of Republic of Korea on the Concept Hierarchy and display the editing screen for it on the right.

For more descriptive properties, EDG includes rich text formatting controls. Give Busan a definition of "Largest city after Seoul", then select the word "Largest" with your cursor and click the  I button to set it in italics. You can also create a link to a concept representing Seoul concept. Just click on and follow the instructions.


Click the Save Changes button at the top of your screen, and you'll see the note you added on the display screen for your new Busan concept.

Try following similar steps to create a new concept as a child of Busan. Give it a label of "Test", and leave the Type value at Concept. On the editing form for this new concept, just click the Save Changes button without adding any new data.

We don't really want this test node, so we're going to delete it. At the top of your screen, next to the Edit button, is the button for the gear menu , which lets you perform several different actions on your concepts. With your Test node selected on the Concept Hierarchy, pick Delete... to delete it, and a message box will ask you whether you're sure that you want to delete the selected node and its associated information. Click OK to complete the operation.

Edit history

Select "Republic of Korea" on the Concept Hierarchy and click the Show History checkbox in the right-top corner of your screen. This displays an alternative version of the concept data form that shows who made what changes when:


Each change entry shows who made it and when they did. It also includes a hypertext link that lets you revert the change.

As you might imagine, the "Show history" view can get cluttered after a while. That's why it's handy that the checkbox lets you toggle it on and off.

Uncheck the Show History checkbox before continuing.

The search pane

Click the dark blue part of the right border of your screen to display the search pane. The following shows the results of searching for all concepts with "land" in their preferred label, with their "has broader" value retrieved with the resource names:



Scroll down to see additional properties that you can use as search criteria and retrieve. Checking a property on the form indicates that you want that property's values included in your search result; entering a value in one of the search fields shows that you want to search for concepts that have that string in their settings for that property. Each field also has menu, accessible by clicking the triangle on its right, that gives you additional ways to specify the data to search for; see Searching for substrings, exact strings, and other alternatives in the user guide for a description of the options.

The Search for: field at the top of the search form lets you search among specialized classes and adds any custom properties for those types to the search form. For example, if you search among the Geography Vocabulary's Country concepts, you will see the custom calling code, capital, and language properties on the search form along with the standard SKOS ones such as preferred label and has broader.

In search results, concept preferred labels will be included by default as the resource name, so there is no need to check "preferred label" on the form. In the illustration above, the user wanted to search for all concepts with "land" in their preferred label and to retrieve the "has broader" value as well. The Search Results panel below shows the first 10 results of this query after the Search button was clicked. In order to see more results use Next button in the bottom-right corner of the Search Results window. The gear button next to the Search and Reset buttons lets you edit the search results as a batch as well as exporting the search results to XML or to a tab-separated value file suitable for importing into a spreadsheet program like Excel. See the Searching Within a Taxonomy section of the user guide for more details on these possibilities.


Click the darker part of the divider bar at the left of the search form (see the figure above) to collapse the form back to the right.

Editing classes


Geography Vocabulary includes the Geography Ontology that is being provided with the product and can be found in the TopBraid project under Examples folder. Since this Ontology was included not as a collection in EDG, there is no way to modify it.

However, if you would like to add more classes or properties to the Geography ontology, you can achieve that by creating a "Geography Ontology" in the Ontologies asset collection. Click on Create New Ontology at the top of the ontologies window and fill in the appropriate boxes.


Once the ontology is created you will be sent to Import/Export tab. Import the RDF file from TopBraid Workspace from the following path TopBraid > Examples> geo-ontology.ttl


Since we have a Geography Ontology created in EDG, we can now use it in the Geography Taxonomy. Select a Geography Taxonomy from the Taxonomies asset collection. In a management screen choose Settings tab and modify Includes. Add Geography Ontology that we just created and remove a system geography ontology that was initially provided with the Geography Vocabulary. Your Includes screen should look as follows.

Notice that Gepgraphy Ontology is underlined now. It means it's an asset collection created in EDG and if you click on that link, you will be sent directly to the Geography Ontology management screen.

Click on Edit Production Copy to go to the ontology editor.

As with the Concept Hierarchy, you can expand the Classes hierarchy by clicking the arrows next to each type name. Mustard circles represent types, green rectangles represent attribute properties, and blue rectangles represent relationship properties. Below we see that the Geo Concept class has been customised with the addition of area and verified date attribute properties, and that the Country type has been customised with three additional properties: calling code, language attribute properties and a capital relationship property. (The additional properties added to Geo concept will also appear on its subclasses such as City, Continent, and Country.)


Buttons across the top of the class hierarchy tree let you create new classes, attributes, and relationships as children of the currently selected class, as well as new concepts for the selected class. The Delete choice of the gear menu at the top of the right screen lets you delete the selected node from the Class Hierarchy tree. The Class Hierarchy section of the User guide chapter explains these features in further detail.

In order to go back to the Geography Vocabulary you can either use browser buttons or go to a Home screen and navigate to Taxonomies asset collection from there.

Reviewing and Publishing Vocabulary Changes

Clicking the hypertext links of your vocabulary name or working copy name at the top of your screen (in this case, "Geography Vocabulary" and "South Korea Updates", respectively) would return you to the management screen for either of these. If you click Geography Vocabulary and then Edit Production Taxonomy on the Geography vocabulary management screen, you would see that the preferred label of South Korea is still there, with that name and no Busan child. You've been editing a working copy, so the official production version has remained unchanged. We'll see how to put your working copy's edits into production shortly.

First, imagine that you're part of a taxonomy management staff and that it's time to review the changes you've made before putting them into production. Click the "South Korea Updates" link at the top of the screen to go to the workflow's utilities page, and then on that screen's Workflow tab click Freeze for Review. Now, everyone—including yourself, the Administrator—only has read access to the the changes in the working copy. The Edit Working Copy link disappears, and a new link—Allow Further Changes—replaces Freeze for Review. Now, no one can edit this working copy, regardless of their roles, until an administrator like yourself clicks Allow Further Changes.

Click View Working Copy at the top of the screen and you'll see that the interface for working with the data is pretty much the same as before except that, when you have a resource selected on the concept hierarchy, there is no Edit button at the top of the screen so that you can't edit the data. (This is the same interface that users who only have Viewer privileges see.)

In a typical production cycle, you would let anyone interested in updates to the vocabulary know that you were finished creating your South Korea Updates working copy and that they should review the changes before you published the changes to the production version of the vocabulary.

In a large metadata management environment, you might have one person creating the working copy, several others editing it, additional people reviewing the changes, and another person publishing the changes to the production copy, but for this tutorial, you're doing all of these yourself.

Click the "South Korea Updates" link at the top of the screen to return to the Working Copy Management screen, and then click the Comparison Report link on the Reports tab. This displays a report that shows where this working copy differs from the production copy—a handy report to run during the final review cycle for a working copy:



Let's say that everyone who needed to review these changes has done so, everyone approves, and you're ready to make the changes official. On the "South Korea Updates" working copy management screen's Workflow tab, click on Approve changes and then Accept changes to production  . After a message box confirms that you want to do this, you'll see a message that this working copy has been committed. When you return to the Geography vocabulary management screen, you will no longer see this working copy listed, because now that its changes have been made to the production copy, they are no longer proposed changes.

Click Edit Production Taxonomy and check Asia's child concepts again. You will see that the Republic of Korea is there instead of South Korea, and it will have Busan as a child along with Seoul.

Learning More

You're now ready to explore the User guide chapter to learn about all the other features available as you use TopBraid EDG - Vocabulary Management package. You'll find out how to view reports on vocabularies, how to export them to and import them from spreadsheets and other formats, how to perform batch operations on them, and more.

  • No labels