Ontopoly: The Topic Map Editor

User’s Guide

Published by:Ontopia


This is the user guide for Ontopia’s self-configuring, ontology-driven Topic Maps editor, Ontopoly. A topic map consists of both an ontology and an instance of that ontology; with Ontopoly, you can edit each of these. The ontology defines the rules for what can go into the instance, and these rules are used by Ontopoly to automatically generate the interface for creating and maintaining the instance. This document provides guidance for creating both ontologies and instances.

Reading this document assumes some basic knowledge about Topic Maps. If you are not familiar with Topic Maps, try reading one of the simple introductions, such as The TAO of Topic Maps, available from the Ontopia web site. If you are technically minded, you might also want to look at the XTM Specification or the new version of ISO 13250, especially the Data Model.

We welcome any suggestions you might have on ways of improving this User Guide. Please send them to dev@ontopia.net.

We hope you enjoy using Ontopoly!

Table of contents

1. Getting started

Ontopoly is built as a client/server application. As a client, you use your web browser, while the server is a web server bundled with the distribution. The server-side application is built using the Navigator Framework and Web Editor Framework, which are parts of the Ontopia Knowledge Suite™. Ontopoly is accessible within Ontopia, an application that provides easy access to Ontopoly, Omnigator, and Vizigator.

Figure 1. Ontopia Home Page

To install and start up Ontopia, please see install.html. Once you have accessed Ontopia, choose Ontopoly from the available options.

2. General concepts

2.1. Application architecture

Ontopoly’s primary purpose is to enable the manual creation and maintenance of topic maps that may be based on a variety of ontologies. In order to be able to provide the most intuitive possible user interface for such a generic application, Ontopoly is ontology-driven. What this means is that the forms-based interface for creating and maintaining a topic map is generated automatically from the underlying ontology and the rules that are defined for it.

For this reason, you need to create an ontology before you can edit a topic map instance in Ontopoly. Often the tasks of creating the ontology and editing the topic map instance (that is, populating the ontology) will be carried out by different people. Ontopoly is therefore divided into two main parts: the ontology editor and the instance editor. The application also has an administration interface, i.e., a page for adding metadata to the topic map (description, creator, version, etc.), validating it, etc.; and an interface for exporting to various interchange syntaxes.

The Topic Map Index Page allows you to open an existing topic map, create a new one, or import one from outside Ontopoly. Once you have selected one of these actions, you are taken to the application pages. The overall architecture and the navigation paths between the various parts of the application are shown in figure 2.

Figure 2. Overview of Ontopoly’s architecture

2.2. Configuring and populating topic maps

Ontopoly’s two primary functions provide a comprehensive Topic Maps editing environment.

  1. Configuring a topic map: ontology and schema creation

    Ontopoly’s Type Configuration Pages are used by the ontology designer to define the topic, name, association, association role, and occurrence types that will be available to creators of the instance topics. To take an example, when an author creates a topic of type composer, the Instance Editing Page will show the fields that apply to a composer, such as name, date of birth, and works; but when editing an opera, the fields will be different.

    As the ontology designer assigns fields (such as associations and occurrences) to a topic type, the designer is also creating the schema. The creation of the ontology and the schema are seamless and appear to the designer as a cohesive operation. For further detail on ontology creation, see section 3.

  2. Populating a topic map: instance creation

    Once an ontology is created, it can be used to guide populating the topic map. The Instance Editing Pages are used by the person authoring the topic map instance. The available topic types are provided from the ontology. The schema constraints give the instance author further support by allowing only specific association types and occurrence types to be used with an instance of a given topic type. For further detail on instance editing, see section 4.

2.3. User interface conventions

Ontopoly has a web-based interface. For a discussion of the various areas of the Ontopoly interface and a complete list of icons, tabs and buttons used in the interface, please see Appendix A.

2.4. Topic Map Index Page

Before you can create either the ontology or the instance, you have to open a topic map, so let’s start there.

When you first access Ontopoly from Ontopia, you are taken to the Topic Map Index Page, see figure 3. On the left, is a column for Ontopoly Topic Maps, in the middle is the list of Other Topic Maps (also referred to as “non-Ontopoly topic maps”), and on the right is the area for creating new topic maps. Another column, Missing Topic Maps, will also appear on this page if an Ontopoly topic map has been deleted from outside Ontopoly. For more information on deleting Ontopoly topic maps, please see section 3.8.1.

Figure 3. Ontopoly Topic Map Index Page

Ontopoly imports topic maps in the XTM 1.0 and 2.0, CTM, LTM, and TM/XML syntaxes; it will also import RDF. By default Ontopoly creates topic maps as XTM files in the Omnigator’s topicmaps/ directory. For information on exporting from Ontopoly, see section 3.9.

2.4.1. Ontopoly topic maps

A topic map created in Ontopoly (an Ontopoly topic map) will differ from one created outside of it (a non-Ontopoly topic map). An Ontopoly topic map carries along with it topics that let it interact with the Ontopoly application and topics that define the schema (the system topics). You can always export a topic map from Ontopoly to remove the system topics, but they are needed for the topic map to be understood within the application. (It’s the system topics that make it possible for Ontopoly to automatically configure its instance editor for maximum ease of use.) Similarly, pre-existing non-Ontopoly topic maps will need these system topics to be added. Ontopoly automatically adds them when opening a non-Ontopoly topic map.

In the situation where you are trying to load an Ontopoly topic map using an older versjon of the ontology, you will be forward to an upgrade page. If you want to perform the upgrade click the OK button. Otherwise click Cancel. Once the upgrade is done you will be forwarded to the Type Type Index Page.

Figure 4. Conversion page

2.4.2. Opening a non-Ontopoly topic map

If you try to open a non-Ontopoly topic map, you will be forwarded to the conversion page, which looks something like this:

Figure 5. Conversion page

Opening a non-Ontopoly topic map converts it to an Ontopoly topic map and creates an index in the process (which may take several minutes). When you click on a non-Ontopoly topic map, you will get information about the conversion process. If the topic map contains features not supported by Ontopoly (see appendix B), you will see a warning and a list of the unsupported features that are used in the topic map. There are options to update your existing topic map or create a copy of it. After this decision, you are taken to the Topic Type Configuration Page.

During the conversion, Ontopoly makes decisions about the ontology, based on what it finds in the topic map, and generates the strictest possible schema. Sometimes it will be stricter than necessary. For example, if occurrences of a particular type (say, email) never occur more than once for any person topic, then Ontopoly may create a rule allowing a maximum of one email occurrence per person topic. You may want to relax the rule, however, using Ontopoly’s ontology editor, in order to allow for the possibility of multiple email occurrences in the future. For this reason you should always examine the ontology generated by Ontopoly when importing an external topic map, and adjust it to reflect the true intent behind the topic map.

2.4.3. Creating a new Ontopoly topic map

Use the Name field in the right hand column of the page to create a new topic map. After naming the topic map, you are taken to the Topic Type Configuration Page. The name you enter will be used for the name of the topic map and will appear in the left-hand column on the Topic Map Index Page when subsequently accessed. (You will be able to change it later, if you like, see section 3.8.) The name will also be used to generate a file name, with the extension .xtm being added automatically.

2.5. Our example topic map

A simple topic map example will be used throughout the next two sections to illustrate Ontopoly’s functionality. It is a topic map that captures information about artists, the albums they have made, and tracks on the album. We've called it Jill’s Music and it’s based on an ontology called MyMusic; both are included in the Ontopoly distribution.

So, why wait? Go on now to section section 3 and start creating your first topic map in Ontopoly!

3. Using the Type Configuration Pages

Each topic map you create will be about some domain of knowledge, such as your corporate intranet, medical research, recording artists, the works of Shakespeare, etc. A topic map identifies subjects and the relationships between those subjects. Each of the subjects will be of a certain type, e.g., Puccini and Verdi are composers, La Scala and Fenice are opera houses, Milan and Venice are cities, etc.

Using Ontopoly’s Type Configuration Pages, you will create the typing topics that will control your topic map: topic, association, occurrence, role and name types. You will also create the rules for how the typing topics are used together.

To provide a practical introduction to Ontopoly’s functionality, we’ve created an ontology for a music organization topic map, MyMusic, and an example topic map that uses that ontology, Jill’s Music.

Here are the topic types we will be working with:

   Individual Artist

The indentation indicates that Group and Individual Artist are subtypes (or subclasses) of Artist.

In addition, we have defined the following association types:

Album created by
Belongs to album
Is a Member of

3.1. Type Index Pages

When you open an existing or newly created topic map, you are taken to the Topic Type Index Page, see figure 6. Here you’ll see menu buttons for each kind of typing topic: topic types, occurrence types, association types, role types, and name types. The Ontology tab is available on every page in Ontopoly. Clicking on it will always bring you to the Topic Type Index Page. From there you can quickly access the corresponding Type Index Pages for other kinds of typing topics, which are typically used less often.

All of the Type Index Pages are more-or-less the same. Each one presents a tree of existing types and a field for creating a new type. The types are displayed as a type hierarchy and includes buttons for expanding and collapsing the tree structure.

Clicking on any of the typing topics (or creating a new one) takes you to the appropriate Configuration Page, as described below.

Figure 6. Topic Type Index Page

Creating an ontology is an iterative process. Through Ontopoly’s interface, you can navigate easily between the Type Index Pages and the Type Configuration Pages. In the following we describe each kind of Type Configuration Page in turn, but in your work you will find yourself moving back and forth throughout the process.

3.2. Type Configuration Pages

There are five kinds of types in Topic Maps: topic types, occurrence types, association types, role types, and name types. Each of these has its own kind of Type Configuration Page, which is accessed via the links at the top on the Type Index Pages. Each Type Configuration Page is unique, but some fields are common to all of them (see figure 7):

The following two fields appear on the Advanced view panel for all types:

The following sections provide more detail on each kind of Type Configuration Page.

3.3. Configuring topic types

The Topic Type Index is shown in figure 6. From here you can enter a name for a new topic type in the field and then click Create, or you can choose an existing topic type to view or edit. Our example already contains an ontology which has been partially populated, so we will go straight to the Topic Type Configuration Page for a pre-existing type, Artist.

3.3.1. Topic Type Configuration Page

Configuration pages control what the instance authors will see as they create topics of a given type. Let’s look at the Topic Type Configuration Page in figure 7.

The main portion of the page is divided into three parts: the top part lists the core properties of the typing topic (its name, subject identifier and description fields plus abstract, superclass and subclass fields which are specific to topic types); the lower part of the page lists those properties, or “fields” (i.e., names, identifiers, occurrences, and associations), that will apply to instances of the type; the right part contains operations, that can be performed on the topic type, and links to other relevant pages.

The properties that are common to all typing topics and thus occur on all Configuration Pages were described above in section 3.2. This applies to Name, Subject identifier, Description, Read-only, and Hidden. The first three fields are shown in the Default view panel and the last two on the Advanced view panel. The following additional properties are specific to topic types:

3.3.2. Properties of the typing topic (Default view panel)

Figure 7. Topic Type Configuration Page - default properties

3.3.3. Properties of the typing topic (Advanced view panel)

Figure 8. Topic Type Configuration Page - advanced properties

3.3.4. Assigning new fields

Figure 9. Topic Type Configuration Page - default properties

In the lower part of the Topic Type Configuration Page (in the default view) you can define and add fields to the topic for use in the Instance Editing Pages. The fields shown here are the fields that are already assigned to the topic type. The Names, Occurrences, Associations, and Identities links at the top will allow you to assign new fields and the icon will let you create a new field by creating a new ontology type. New fields will be placed at the bottom of the fields list.

3.3.5. Editing existing fields

Now let’s move on down to the existing fields. As you can see from the figure below the Artist topic type has five fields assigned. Each field is displayed in a separate table row.

Figure 14.

At the left you find the icon. Use this icon to reorder the fields. Drag the icon on top of the field that you want the dragged field to be ordered after. Note that in order to make a field become the first field you have to first drag it on top of the first field and then afterwards drag the first field on top of the new second field.

The icon will let you edit the topic that represents the field. Clicking this icon will navigate to the instance page of the field. This page will reveal more detailed information about the field.

Next is the field label. The label is a link that lets you navigate to the name type, occurrence type, association type or identity type topics declared by the field.

To the right of the field label is the value type of the field. This will tell you what kind of values can be assigned to this field. In our example the Name is a name string, the Subject identifier is a URI, and the Description is a string. The association fields shows the kind of topics that can be associated through the field. The Contains track can contain Tracks and the Album created by can contain Artists. If the value type is Many then multiple topic types can be associated through that field. Hold the mouse over the Many label to see which topic types that is.

The drop-down list shows the cardinality choices for the number of times the field can or must be used in the Instance Editing Page. There are four possible choices: Exactly one, One or more, Zero or more, and Zero or one.

Each line ends with the icon, which is used to remove fields, i.e. unassign them. Removing a field will make it once more available as a option to reassign. If the icon is shown instead of the remove icon then it means that the field has been assigned to a supertype. Clicking the icon will navigate to the supertype that declares the field. The field can then be removed there instead.

We now know how to add fields to a topic type. However, most of these fields have to be defined by the ontology designer through the use of the other Configuration Pages, so let’s move on.

3.4. Configuring occurrence types

Occurrences can refer to resources external to the topic map, such as a web page, or they can be internal to the topic map, in which case they can be thought of as attributes (or properties) of the subject that the topic represents. You can create new occurrence types or choose one for edit from the Occurrence Type Index, see figure 15, which will take you to the Occurrence Type Configuration Page, see figure 16.

Figure 15. Occurrence Type Index Page

3.4.1. Occurrence Type Configuration Page

The Occurrence Type Configuration Page for Description looks as follows:

Figure 16. Occurrence Type Configuration Page - default properties

The core properties of the occurrence type topic are shown in the upper part of the page; the lower part contains the information about how fields of this type will be used when editing instances. The properties of the occurrence field is displayed in the grey Occurrence field field box. This box represents the field that is assigned to topic types. The actual topic types that is assigned the field (and indirectly the occurrence type) can be seen in the Used by field.

Core properties common to all typing topics are described in section 3.2.

3.4.2. Properties of the occurrence field (Default view panel)

As the occurrence fields are ones in which the author will be providing content rather than picking topic names or role labels, it is necessary for the ontology designer to describe the dimensions that the field will be given on the Instance Editing Page. Two fields are provided for this purpose:

3.4.3. Properties of the occurrence field (Advanced view panel)

Figure 17. Occurrence Type Configuration Page - default properties

The occurrence type's Advanced view panel contains only the two standard Read-only and Hidden fields.

3.5. Configuring association types

Associations describe a relationship that can or must exist between topics. You can create new association types or choose one for edit from the Association Type Index, see figure 18, which will take you to the Association Type Configuration Page, see figure 20

Figure 18. Association Type Index Page

Most associations are binary, that is, there are two role players, such as in parent-child or employer-employee relationships. You can also create associations with only one role player, or with three or more role players. We will focus on binary associations for the scope of this document.

Binary associations are bi-directional. For example, an association named composed-by might sound like it is only uni-directional, i.e., Tosca is composed by Puccini. However, it also represents the relationship expressed as, for example, Puccini composed Tosca. Topic Maps accomplishes this bi-directionality, unambiguously, by assigning roles to the players. The relationship expressed in figure 19 can be described as, “In the composed-by relationship, the role of composer is played by Puccini and the role of work is played by Tosca.”

Figure 19. Associations are bi-directional

Ontopoly’s Association Type Configuration Page helps you to define the association type, roles their role types and their corresponding role player types, and the labels for role fields as seen from the perspective of each role player.

3.5.1. Association Type Configuration Page

The Association Type Configuration Page for Album created by looks as follows:

Figure 20. Association Type Configuration Page - default properties

The core properties of the association type are again shown in the upper part of the page; the lower part contains information relating to the role fields declared for the associaion type.

Core properties common to all typing topics are described in section 3.2.

3.5.2. Properties of the typing topic (Default view panel)

The Association Type Configuration Page contains one new checkbox in the top portion of the form, Symmetric, and an association field labelled Association field. Roles

In general, there is one role box for each role player. In most cases, there will be two role players and therefore two role boxes. In symmetric associations (and unary associations), there is only one role box. It is also possible to have more than two role players (in what are known as “n-ary associations”); an example of a ternary association (one with three role players) would be a perpetrator, a victim, and a cause of death in a "killed / killed-by" association.

Each role box has four fields:

Once you have created an association type, visit the Topic Type Configuration Pages of the topics that play roles to make sure the cardinality for the use of the association is correct. These should be reviewed from the perspective of each role player as they may differ, e.g., a student goes to one school (Exactly one), but a school may have many students (One or more).

3.5.3. Properties of the typing topic (Advanced view panel)

Figure 21. Association Type Configuration Page - advanced properties

This section allows you to configure an association type as being hierarchical. To do this, you must also set the role types correctly, so that Ontopoly knows which role is the parent role and which is the child role. The purpose of this to enable Ontopoly to show you the hierarchy formed by these associations.

An example might be the hierarchy formed by the geographical "contained in" association. The parent role here would be "container" and the child role would be "containee". Setting this up would allow you to browse your collection of geographic places as a tree on the Instance Index Page (see section 4.1.1) and in the Topic Selection Dialog (see section 4.1.4). Another example might be the broader/narrower relationship from taxonomies and thesauri, which you can find in the UK Government Category List, which comes with Ontopoly.

Note that to register an association type as hierarchical one must add the Hierarchical Relation Type topic type to the association type. At the moment this can only be done in Administrator mode, and using the Add or remove topic type action item on the right side of the page.

3.6. Configuring role types

Role types are used in associations to represent the semantics of why a topic participates in an association. For role types one either selects an existing topic type (e.g. "opera") or one creates a topic that represents a more specific role (e.g. "composer"), i.e. something that describes what it means for a topic to be part of the role. As you can see one might choose a role type that represents what the player does as opposed to what the person inherently is. Beethoven is a person, but he is also composer because he composed something. Topic types should be universally valid for the topic. Role types on the other hand can, and often should, be more context dependent. Role types should be as generic as possible so that they can easily be reused across association types. For example, whether you have a "composer/opera", "author/book", or "artist/painting" association, the roles the topics play in all three of these examples might be "creator" and "creation", even though the association types could be different.

You can create new role types or choose one for edit from the Role Type Index page, see figure 22, which will take you to the Role Type Configuration Page, see figure 23.

Figure 22. Role Type Index Page

3.6.1. Role Type Configuration Page

In our sample topic map there is only one topic, Member, that is specifically registered as a role type. All other role types used in the topic map are topic types. The Role Type Configuration Page for Member looks as follows:

Figure 23. Role Type Configuration Page - default properties

Core properties common to all typing topics are described in section 3.2.

3.6.2. Properties of the typing topic (Default view panel)

There are not really any new properties here. The first three are core properties common to all typing topics. The Role field represents the relation between the role type and the role fields in which it has been declared. The properties of the role field we have already seen in section

3.6.3. Properties of the typing topic (Advanced view panel)

Figure 24. Role Type Configuration Page - advanced properties

The two new fields on this page are the inverse of the Superordinate role type and Subordinate role type fields we saw in section 3.5.3.

3.7. Configuring name types

Name types are used to define the names of topics in various contexts. Frequently used name types include nickname and short, but one of the most popular uses is to provide the name of the topic in multiple languages. You can create new name types or choose one for edit from the Name Type Index, see figure 25, which will take you to the Name Type Configuration Page, see figure 26

Figure 25. Name Type Index Page

3.7.1. Name Type Configuration Page (Default view panel)

The Name Type Configuration Page for Nickname looks as follows:

Figure 26. Name Type Configuration Page - default properties

Core properties common to all typing topics are described in section 3.2.

3.7.2. Name Type Configuration Page (Advanced view panel)

Figure 27. Name Type Configuration Page - default properties

There are no new properties in the advanced view outside of the core commmon properties described in section 3.2.

3.8. Topic Map Description Page

Once you are within a topic map, you can choose to enter descriptive information about it. Use the Description tab to access the Description Page (see figure 28).

This page can be used to change the name of the topic map, but the file name will remain the same as assigned when creating it.

Figure 28. Topic Map Description Page

There are four editable fields:

3.8.1. Deleting a topic map

The Delete button on the Description Page removes the topic map from the list of Ontopoly Topic Maps and physically removes the file from the disk.


Ontopoly keeps track of your Ontopoly topic maps. Manually deleting an Ontopoly topic map from the file system (as opposed to using the Delete button on the Description Page) will result in the display of a Missing Topic Maps column on the Topic Map Index Page. Therefore, it is best practice only to delete Ontopoly topic maps through the Delete button on the Description tab.

Clicking the Delete button will open up a confirmation window. Choose OK to delete the topic map. You will then be taken to the start page (see appendix B). Clicking the Cancel button will cancel the operation and close the confirmation window.

Figure 29. Deletion confirmation window

3.8.2. Enabling shortcuts

The Enable shortcuts action item on right-hand side of the Description Page (figure 28) will enable some useful shortcuts in the user interface. The field labels in the editing pages will become links. The icon will let you go directly to the topic that represents the field. Clicking the field label will navigate to the name type, occurrence type, association type or identity type topics declared by the field. You can later disable shortcuts by clicking the button again.

Here is an example of what an editing page looks like with shortcuts enabled:

Figure 30. Topic Type Configuration Page with shortcuts enabled

3.8.3. Ontology annotation

The Enable ontology annotation action item on right-hand side of the Description Page (figure 28) turns on ontology annotation, which is a very powerful feature, but one that can be a little confusing at first. The basic idea is that the normal Ontopoly (without this feature) allows you to say anything you want about instance topics, but for typing topics you are pretty much restricted to names, subject identifiers, and the description field. This may not sound like much of a problem, but there are a lot of useful things that can be done if you can annotate your ontology topics.

Generally, ontology annotation enables you to build more dynamic applications, by moving logic out of your code and into the topic map. To take a trivial example, imagine building a search page for your topic map. On this page you'll need to display things like "found X people", "found Y documents", etc, and to do this you need to display the plural names of the topic types. You can of course do this with a big multi-way test (if current topic type is "person", display "people"). But the easiest way is to make a name type "Plural name" and to give each topic type such a name.

With ontology annotation this is easy. Once you turn ontology annotation on, the topic types "Topic type", "Association type", etc show up in the list of topic types. This lets you give them fields in the same way as normal topic types, and you can edit them in the normal way.

This what the Topic Types Index Page looks like with annotation enabled. The ontology types are displayed in italic.

Figure 31. Topic Type Index Page with annotation enabled

3.8.4. Administration mode

The Enable administration mode action item on right-hand side of the Description Page (figure 28) turns on admistration mode, which is an extremely powerful feature as it gives you access to everything in the topic map, including the Ontopoly model itself.


Be careful when using this feature.

As you can see there is a lot of new topic types visible on the Topic Types Index Page when administration mode is enabled:

Figure 32. Topic Type Index Page with administration mode enabled

3.9. Exporting a topic map

The Export Page (see figure 33) is accessed via the Admin tab. The desired export format (LTM, XTM 1.0, XTM 2.0, or RDF) is chosen via radio buttons.

Figure 33. Export Page

You can choose to export the topic map with or without the system topics (those topics that make up the constraints or rules for using the ontology). In general, other downstream applications such as browsers will neither understand nor need the schema topics. The export is done to a browser window and can be saved from there.

3.10. Saving a topic map

Any modifications made in an editing page will be sent to the server immediately and written into the topic map. The application is AJAX based, so modification are sent to the server as soon as they are made. If an error occurs, the user may be redirected to a page showing the errors instead of the intended destination.

The back button will work in the way it generally does on the web, and will return to the previous page or to the previous state of the current page. Note that previous page may be slightly out of date if any changes were made to the topic since it was displayed the first time.


Changes to your topic map are not automatically persisted to disk on the server unless you are using Ontopoly with the relational database backend of the Ontopia Knowledge Suite. With the free version of Ontopoly, which operates in-memory, it is necessary to press the Save button in order to save the topic map to disk: pressing the Confirm does not save to disk; it merely submits the current page and updates the topic map in memory.

4. Using Instance Editing Pages

The Instance Editing Pages are used to create instance topics conforming to the ontology and constraints developed using the Type Configuration Pages.

4.1. Topic Type Index Page

When you choose the Instances tab, you will land at the instance index of all topic types. If your ontology includes a type hierarchy, you will be able to show the complete tree by clicking on Expand all nodes, with the result as shown in figure 34. Topic types that are allowed to have instances are shown as links.

Figure 34. Topic Type Index Page

From this index, you can choose a topic type to see a list of instance topics of that type (see figure 35).

4.1.1. Instance Index Pages

Figure 35. Instance Index Page

Choose an existing instance topic from the Instance Index, or Create a new instance, to access the Instance Editing Page.

4.1.2. Instance Editing Page

The Instance Editing Page is used to edit individual instance topics, and is the most central page in Ontopoly, since most editing will happen here. The contents on the page are entirely determined by the ontology and schema for the topic type (see section 3.3.1 for more on the Topic Type Configuration Page). All the allowable fields for a topic type are available on the Instance Editing Page, along with the allowable values for those fields.

Figure 36. Instance Editing Page

When editing a topic there may be validation errors. These usually occur when values are missing or when there are too many values for a given field. The error messages shows up right above the individual field. The topic map can be saved while there are validation errors.

Figure 37. Field with validation error

4.1.3. Changing a topic’s type

Frequently, it is easier to create a new instance from another instance, rather than going back to the Instance Index Page. However the next instance to be created might be of a different type than the current one. In such cases, the instance author can use the Change the topic type choice in the Action Items Panel immediately upon accessing the new Instance Editing Page, picking the new type from the drop-down box.

There are other times when changing the topic type will be useful. For example, in an employee database, employees might be typed by their status, such as probationary, tenured, retired, etc. As their status changes, their topic type might change as well.

Changing a topic’s type can lead to a number of knock-on effects that require action. For illustration purposes in figure 38, the Individual Artist type topic Sir Paul McCartney has been changed to an Album type topic. Now a new set of fields will be displayed for the topic. Some of the fields are the same: Name, Subject identifier and Description, while Contains track and Album created by replaces Nickname, Is/was a Member of and Created album. The user interface now complains that information is missing in the Contains track. Note that the information from the old fields are still stored on the topic, but the fields are not presented in the user interface. Changing the topic type back to Individual artist will again show the original fields with the original values.

Figure 38. Messages when changing a topic’s type

4.1.4. Assigning topics to associations

You can create new topics by clicking the icon. If there are multiple topic types that can participate in the association, then you will be presented with a context menu, like the one below, where you can select the topic type of the new instance.

Figure 39. Create player context menu

A new instance will then be created and associated to the current topic. A popup window will then open and let you edit some basic information about the new instance. Close the popup by clicking the OK button or the X in the top right corner.

Figure 40. Create player popup window

By default topics at the other end of associations are selected using drop-down boxes, but this can be changed in the configuration of the association type in the Interface control field. The alternative for interface control are: Drop-down list, Search dialog, Browse dialog, and Auto-complete.

This is what the default drop-down list looks like. You may have to press before it shows up.

Figure 41. A drop-down list

The interface controls Search dialog and Browse dialog use a popup dialog where the user can either search for the topic to associate with, or browse for it.

If we change the example topic map so that to select an album created by an artist you have to use the dialog, the instance editing page from figure 36 would have a little search button instead of the drop-down box.

Figure 42. The search button

Pressing the icon would open a new window as shown in the figure below.

Figure 43. The search dialog

Here you can do a search, and create associations to the topics you find, or you can click "Browse" and see a list of the topics you could create an association to. Below is shown the screen you get in this case by clicking "Browse". This is also the dialog you would get if the interface control had been Browse dialog.

Note that it's possible to control what shows on the browse screen by configuring the topic type. It's possible to make the topics be shown in a hierarchy, or to make it impossible to display the list of topics (because the list is too big). See section 3.3.3 for more information.

Figure 44. The browse dialog

If the interface control is Auto-complete you will get an input text field. You may have to press before the input field shows up. Below you can see an example of what this interface control looks like. Once you start typing a list of matching topics show up in a list below the input field. Note that the auto-complete field runs a full-text query to retrieve the topics to display in the list. (Note: the syntax of a full-text query currently depends on the full-text engine used. This is likely to change in the future.)

Figure 45. The auto-complete input box

4.1.5. Editing name, occurrence, and identity fields

Names are always entered in a standard text input field.


The new field value is sent to the server as soon as the field looses its focus, so make sure, that when you're done editing, to click outside of the input box or press the Tab key to move to another field. This rule applies to all text input boxes in the application.

Figure 46. Name field

As mentioned in section 3.4.2, an occurrence field have a data type. The default is String. Occurrences with the data types String and Number are displayed as a standard input text field. Here is an example:

Figure 47. String and numeric occurrences

Identity fields and occurrences with the data type URI are displayed as an input text field, but with an icon next to it. Clicking the icon will open the URI in the web browser.

Figure 48. URI occurrences (and identity fields)

Occurrences with the data types Date and Datetime are displayed as a standard input text field, but with a date picker widget attached.

Figure 49. Date and datetime occurrences

HTML occurrences can be edited using an embedded HTML editor (currently TinyMCE). This editor provides rich formatting capabilities, but allows you to edit the actual HTML document.


Note that this component will not automatically save your edits. Instead click the to have your changes saved to the server.

Figure 50. HTML occurrences

Image occurrence fields lets you upload images and display them in the instance editor. Click the Choose... button to get a file chooser widget that lets you select an image file from the file system. Once the file has been selected, click the Upload to uploaded the image and create an occurrence for it.

Figure 51. Uploading an image

Here is an example of what the user interface looks like after an image has been uploaded:

Figure 52. Image occurrences

5. Using Ontopoly with multiple users

Although Ontopoly ships in a single-user configuration, there is support for multiple users under the hood. This support consists of:

A. User interface conventions

This section describes general aspects of Ontopoly’s user interface.

1. Ontopoly page layout

Most Ontopoly pages have a similar layout. The major sections are identified in figure 53 and described below.

Figure 53. Page layout

1.1. Application navigation

In the upper right hand corner of all Ontopoly pages and on the Ontopia Home Page, there is an application navigation bar.

Table 1. Application navigation bar

HomeReturns you to the Ontopia Home Page.
ManageAccesses the Omnigator Manage page.

This item will eventually take the user to an common Manage Page, that can be used for Ontopoly or Omnigator.

FeedbackAs you use Ontopoly, we hope that you will use this feedback form to send us comments as they occur to you. However, please do not use the feedback mechanism to report bugs. Ontopia provides a direct link to Ontobugs.
SupportIf you need an answer to a question, please use this form or send email to support@ontopia.net.
AboutInformation about the version of Ontopoly currently in use.

1.2. Tabbed navigation

Once inside a topic map, there are four major tabs.

Table 1. Tabbed items

DescriptionPage where descriptive information about the current topic map as a whole can be captured, see section 3.8.
AdminUse this page to export the topic map into a preferred serialization syntax, see section 3.9.
OntologySet of pages for configuring the ontology, i.e., defining the topic, occurrence, association, role, and name type topics. When in Ontology area, a secondary set of buttons occur that provide discrete access to the preferred page, e.g., topic type, association type, etc., see section 3.
InstancesSet of pages for creating and editing instances of topic types defined in the Ontology, see section 4.

The items in the tabs are also repeated at the bottom of each page upon which the tabs occur.

1.3. Editing box

There are three items in the Editing Box:

Table 1. Editing box items

Open...Takes you back to the Topic Map Index Page. If you do not save before you use this button, all edits since your previous save will not be written to disk.
SaveSaves the current topic map to disk.

Only available for in-memory topic maps.

Search box and Find buttonUse to find the uses of a term within the open topic map.

1.4. Topic title

The name of the current topic type or topic instance appears in red.

1.5. Action items panel

The item choices available in grey boxes on the right hand side of the screen are dependent on the type of page you are viewing. The following table includes all possible items as a reference.

Table 1. Action items

Topic typesShows the topic types of this topic. If there are multiple types you can switch between them by clicking the link for each topic type.
ViewsShows the field views declared for fields assigned to this topic type. If there are multiple views you can switch between them by clicking the link for each view.
View instances of this typeMoves you from a Type Configuration Page to an Instance Index Page. Provides the index of instances of the current type.
View instances of same typeMoves you from a Type Configuration Page to an Instance Index Page. Provides the index of instances of the topic type of the current type.
Edit the type of this instanceMoves you from an Instance Editing Page to a Type Configuration Page. Provides the Topic Type Configuration Page for the type of the current instance.

New instance field

Available on the Topic, Association, Occurrence, Role, and Name Type Pages. Supply a name to create a new one of the same type. You will be taken to the appropriate Type Configuration Page, which will have the Name you fill in here.

Also available on Instance Editing Pages. You will be taken to a new Instance Editing Page, which will have the Name you fill in here.

Create new [typing_topic] typeLets you create a new topic of the same type as the current topic, or a full copy of the current topic. Provides a blank Type Configuration Page for the current kind of typing topic (i.e., topic, occurrence, association, role, or name). Similar to the previous, but is accessed from a Type Configuration Page. No Name is filled in if this is not a copy.
Change the topic type drop-down listAvailable from Instance Editing Pages, it provides an easy way to change the type of the current topic. You will be notified of fields used on the current topic that are not available when you change type, so that you can make the necessary decisions and edits.

Delete this topic

Deletes the current topic.

Browse this topic in Omnigator

Opens a new browser window at the Topic Page for the current topic in the Omnigator. As you make changes to the current topic, you will be able to see the changes in the Omnigator window following a browser refresh. If you move away from the topic in Ontopoly, the Omnigator will remain on the original topic even after refreshing the browser.

View this topic in Vizigator

Opens a new browser window with the current topic as the focus topic in Vizigator.

1.6. Topic fields

The fields specific to the topic being edited are dynamic. How to assign new field and how to unassign them are covered in detail in sections section 3 and section 4.

1.7. Ontology typing topics access

Not shown in figure 53, but available on all the Type Index Pages is a secondary navigation bar to facilitate navigation from one Type Index Page to another (see figure 15 for an example).

Table 1. Access to typing topics

Topic TypesAccess to the Topic Type Index.
Occurrence TypesAccess to the Occurrence Type Index
Association TypesAccess to the Association Type Index
Role TypesAccess to the Role Type Index
Name TypesAccess to the Name Type Index

2. Icons

The icons described in the table below occur throughout all Ontopoly pages.

Table 1. Icon conventions

ExpandThe boxed plus sign expands the under the current topic.
CollapseThe boxed minus sign collapses the hierarchy under the current topic.
Blank boxThe empty box precedes a topic that does not have any children in the hierarchy, and so, cannot be expanded or collapsed.
GotoThe right double arrow icon is always used to navigate to another page. If the icon is located next to a text field that contains a URI, the client browser will open the page pointed to by the address. In the fields editor on the Topic Type Configuration Page the icon is used to navigate to the topic type that declared the field. This means that the field is an inherited field.
ReorderUsed to change the order of fields in the Topic Type Configuration Page, and to change the order of field values on the instance editing page.
Show input field

On an Instance Editing Page, the circled plus sign is used to show a new input field so that one can add a new field value.

Hide input field

When used on the Instance Editing Page, the circled minus sign is used to hide the input field.

When used on the Topic Type Configuration Page, it is used to remove a value from an existing field or the use of the field itself.

Remove value

When used on the Instance Editing Page, the small circled minus sign is used to remove values from fields. In the fields editor on the Topic Type Configuration Page the icon is used to unassign fields from the topic type.

CreateThe circled asterisk is always used to create a new topic. Where it occurs will control what type of topic is created at that point. Where a choice of topic types is available, a pop-up menu will be presented.
Contextual helpThe question mark in a green circle provides access to this User Guide.

3. Keyboard navigation

Ontopoly has no special support for keyboard navigation. In other words, the keyboard navigation is as provided by your browser. This means the following:


First tab key press puts the cursor into the first control on the page. Following tab presses go to following controls, including buttons. Drop-down lists can be navigated with the arrow keys, and pressing a letter will jump to the first item whose name begins with that letter.


As for Opera, except that links are included in the tab cycle.

Internet Explorer

As for Firefox, except that URL bar is first in tab cycle.

B. Scope of use

Ontopoly is designed for creating and editing topic maps conforming to ISO/IEC 13250:2003.

The initial release of Ontopoly does not have support for all of the features defined in the ISO standard. As more is known of user requirements, some of these features may be added. We encourage users to provide feedback using the Feedback button available on all Ontopoly pages. Unsupported features and usage constraints currently include:


Not supported.

Variant names

Not supported.


Not supported.


Not supported.

C. About this document

This user guide provides a general theory of operation of Ontopoly. It gives an introduction to its use and guidance on how to access the various functions of the product, but is not meant to be an exhaustive reference manual. Portions of this document serve as the target of links from the contextual help within the product.

This document is focused on the use of Ontopoly and does not provide training on the development of ontologies and topic maps in general. To read more about those subjects, please see the Ontopia Website, particularly the areas on topic mapping.