Getting started with ontologies

DISCLAIMER: ontology features are currently in a mininum viable product state. Everything needed to get started is available, but the feature may undergo further development in order to expand its usefulness and to facilitate adoption.

Ontology files

The industry standard for defining ontologies is known as the Web Ontology Language (OWL), which is in turn based on the Resource Description Framework (RDF). Model-Prime currently supports Turtle (.ttl) syntax for uploading ontologies, which is one of the many semantically equivalent versions of OWL.

To begin using the ontology features of Model-Prime, the first thing that you will need is an ontology editor that can export to .ttl format. Several ontology editors are freely available, but Model-Prime recommends WebProtégé as the ontology editor which best interoperates with our services.¹ Note that Model-Prime does not read from WebProtégé or any other external website directly. Instead, the source of truth is just a .ttl text file that you export from your editor and then upload via the ontology API.

1. Download from Projects view

2. Select Turtle format

3. Locate plain-text .ttl file

For more information on what to include in your ontology, see the next page on Ontology Properties.

Ontology versions and publication

Model-Prime automatically maintains a lineage of versions for the same ontology. To create an ontology version, the process is:

1. Upload an ontology version as a draft.
2. Publish the draft, which promotes it to the live version.

These two steps are the same whether you want to create a new ontology or publish a new version of an existing one.

WARNING: changes to an ontology definition can potentially impact your entire orginazation. In particular, if a class is ever removed from an ontology, all instance data for that class will be effectively lost, becoming meaningless orphaned ID strings. To prevent such a scenario, it is recommended that all ontology changes in your organization be reviewed and applied through a central authority, and that classes be relabeled or deprecated rather than deleted outright.

Upload draft version

Once you have a suitable ontology file, you can upload it to Model-Prime using the Swagger page for the ontology service. Doing so will create the ontology version in a draft state.

When you upload the draft, you must provide a Version header, which is a semantic version number such as 1.0.0. For the initial version, each of the Major, Minor, and Patch numbers must be set to 0 or 1. If this is an update of an existing version, then it must increment the Major, Minor, or Patch number and reset the remaining numbers (if any) to 0 or 1. For example:

• 1.4.12 -> 2.0.0 is allowed.
• 1.4.12 -> 1.4.13 is allowed.
• 1.4.12 -> 1.5.0 is allowed.
• 1.4.12 -> 1.5.1 is allowed.
• 1.4.12 -> 1.5.12 is not allowed.

Also, it it recommended that you provide a brief Version-Message header describing what has changed in this version.

The ID of the ontology is parsed from the document itself. In other words, Model-Prime automatically determines whether your document is a brand new ontology or a new version of an existing one.

Note that drafts are subject to the following limitations:

• Draft versions are unavailable for use by Model-Prime services such as Search and Metadata Management in any way until they are published.
• Only one draft version of a given ontology can exist at one time. Uploading a draft will overwrite any existing draft of the same ontology, even if it was uploaded by a different user in your organization. Model-Prime's API is not designed for collaborative ontology editing; this will need to be done in WebProtégé or other editing software.
• No branching of the version lineage is possible. If you need a full-featured version control system, you can manage your ontology files in a git repository prior to uploading them to Model-Prime.

Publish version

If the draft uploads successfully, then it has met the eligibility criteria for publication. (See the next page on ontology properties for details.) To publish it, use the POST ontology versions endpoint. You will need the ontology_id and e_tag² of the draft, both of which are given in the Draft Upload response.

That's it! Your ontology is now ready to use.

Draft publication is irreversible. The only way to revert to a previous version is to re-publish an older ontology file as the next version. The version history is permanent and cannot be rewritten. If you wish to read the history of published versions, it is available via the GET ontology versions endpoint

Creating ontology fields

Once an ontology has been published, you can create metadata fields linked to that specific ontology. This is done using the POST fields endpoint: just set an alias for the field, an optional description, and specify the ontology_id that you want to link.

• The new field's data type will be ONTOLOGY.
• Values for this field are constrained to the classes of the corresponding ontology.
• Ontology-related features such as subclass search are available for this field.

Values for ontology fields

A value of an ontology field can be created in the same way as any other metadata value, using the POST values endpoint. For the value, enter the ID or label (interchangeably) of a valid class within that field's ontology, as a string. If the value entered is not a valid class ID or class label, it will be rejected. However, labels are case-insensitive, and the space, hyphen, and underscore characters are treated as interchangeable when checking for a label match.

Note that it does not matter whether the ID or label is entered. If a class has multiple labels, it also does not matter which one is used. In all cases, the same value will be created, and it will always be displayed as the primary label of the class, i.e. the one which appears first in the ontology definition file. If the class has no labels at all, then its ID will be displayed instead.

For example: if there is a class Bicyclist with ID abc123 and alternate label Cyclist, then you can enter any of these three strings, or a case-insensitive match such as bicyclist, but the value will always be displayed as Bicyclist.

NOTE: although human-readable class labels are always displayed in the API, it is actually the ID that is stored within the Model-Prime data platform. If you want to query for specific ontology classes using the Analytics Platform rather than the API, then you will need to use their IDs.

---

Footnotes

1. In particular, WebProtégé generates a unique and consistent Internationalized Resource Identifier (IRI) for each class. This is important because Model-Prime recognizes any change to the label(s) of a class as long as its IRI remains the same. If the IRI ever changes, however, then this would effectively delete the class and create a new one. ↩

2. If another user has uploaded a different draft of the same ontology before you can publish, then your e_tag will be out of date and your request will fail with status 412 (Precondition Failed). ↩