Skip to content

UsingCatalogFiles

Jump to bottom
Michael DeBellis edited this page May 26, 2026 · 1 revision

Using Ontology Catalogs for Local Development

This page explains how Protégé uses ontology catalog files and how catalogs can make ontology development more reliable when your ontology imports external vocabularies such as Gist, SKOS, Dublin Core, or PROV-O.

How Protégé Uses the Catalog File

A common source of confusion is how Protégé actually finds and uses a catalog file. The catalog is not referenced from the ontology, and there is no RDF or OWL construct that points to it. Instead, Protégé looks for a catalog file as part of its local project configuration and applies it automatically when resolving imports.

This design has an important practical consequence: ontology files can be moved, renamed, or reorganized without modifying the ontology itself, as long as Protégé can still locate the catalog file and the catalog entries correctly map ontology IRIs to local files.

In other words, the ontology always refers to imported vocabularies by their canonical IRIs. The catalog provides a local, tool-specific resolution mechanism that Protégé applies at load time. If files are moved and a mapping no longer resolves, Protégé will either fall back to retrieving the ontology from its IRI or prompt the user to locate a local copy. In all cases, the ontology itself is left unchanged.

This separation is intentional. Ontology IRIs establish global identity and reuse, while catalogs support local development workflows. Catalog files can therefore be edited, moved, or discarded without affecting the semantics of the ontology.

Using catalogs means that imports remain transparent and standards-compliant, while development is more robust against network failures, changing URLs, and unavailable external sites. This is the approach to use when you want to maintain consistency with future revisions of a vocabulary while controlling when your project upgrades.

Using an ontology catalog allows you to pin what you use today and upgrade on your schedule. The basic workflow is:

  1. Create a local copy of the vocabulary you currently use.
  2. Know when the vocabulary changes.
  3. Upgrade to the new version while minimizing disruption.

Create Local Copies

To begin, create a local copy of every ontology that you reuse. Map each ontology’s namespace IRI to your local file in catalog-v001.xml. Protégé and other tools then load your local copy, so you are not dependent on the Internet or on the provider’s site being available.

Develop a consistent pattern for all your GitHub repositories, so that your ontologies and the catalog file are always in the same place. The exact pattern is not important. What matters is using the same pattern consistently.

For this example, assume the domain ontology is my_domain.ttl and that it reuses Gist and SKOS. The repository might be organized as follows:

repo/
  ontologies/
    catalog-v001.xml
    my_domain.ttl
    external/
      gist/
        gist.ttl
      skos/
        skos.ttl

In my_domain.ttl, the ontology would import the reused vocabularies by their canonical IRIs:

@prefix owl:  <http://www.w3.org/2002/07/owl#> .

<https://example.org/my_domain> a owl:Ontology ;
  owl:imports
      <https://ontologies.semanticarts.com/gist/> ,
      <http://www.w3.org/2004/02/skos/core#> .

Then catalog-v001.xml maps those official IRIs to local files:

<?xml version="1.0" encoding="UTF-8"?>
<catalog prefer="public" xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
  <!-- Map namespace IRIs to your local mirrors using relative paths -->

  <!-- SKOS -->
  <uri name="http://www.w3.org/2004/02/skos/core#"
       uri="external/skos/skos.ttl"/>

  <!-- Gist -->
  <uri name="https://ontologies.semanticarts.com/gist/"
       uri="external/gist/gist.ttl"/>
</catalog>

The specific directory structure is not significant. What matters is that the catalog file and the local mirrors follow a consistent pattern within the repository. This makes it clear what the actual ontology IRI is while insulating you from issues with the Internet or external sites.

In the catalog file:

  • The name attribute is the official IRI for the vocabulary.
  • The uri attribute is the local path where you have stored a local copy.

By combining this approach with GitHub repositories cloned to each developer’s workstation, every developer can have local copies available even when disconnected from the Internet.

Know When Something Changes

To use catalogs effectively, you need to know when a vocabulary you depend on has a new version.

The most common way to do this is to set up alerts through GitHub, since many vocabularies are maintained there. For some vocabularies, however, the notification mechanism may be a mailing list, RSS feed, or project website. These notifications tell you when a new release is available; you can then decide whether and when to upgrade.

On GitHub, you can usually configure release-only notifications:

  1. Go to the repository for the vocabulary.
  2. Click the Watch button near the repository name.
  3. Select Custom.
  4. Select Releases.
  5. Optionally select Security alerts, which is often a good idea for actively maintained vocabularies.

This setup should send email only when a new release is published, rather than notifying you about every issue, pull request, or commit.

Some older W3C-hosted and foundation-hosted vocabularies, such as Dublin Core, announce changes on mailing lists. These are usually easy to find and can often be configured so your inbox is not swamped with irrelevant messages.

Upgrade Safely and Carefully

When you are notified of an update and decide to move forward, use a controlled upgrade process.

  1. Stage the new mirror.
    A mirror is a local copy of the file. Download the new release into a staging folder. Do not overwrite your current mirrors yet.

  2. Run checks.
    Some vocabularies, such as Gist, provide automated scripts for upgrading. These scripts may automate required refactoring or provide tests to find issues caused by the new version. In addition, run your own SPARQL queries and/or SHACL rules against your test data. After the automated checks and scripts complete, run the OWL reasoner to make sure there are no logical errors.

  3. Diff the ontology.
    Use an ontology diff tool, such as Protégé Compare, ROBOT diff, or OWLAPI-based tools, to see what changed. Look for new terms, deprecated terms, range or domain changes, property chains, and other changes that could affect your ontology.

  4. Patch if needed.
    If an upstream change breaks OWL DL, renames a term, or introduces another issue for your project, keep a documented patch in your mirror. Where appropriate, add SPARQL UPDATE migration scripts to your repository.

  5. Promote to production.
    Replace the mirrors under /ontologies/external/... and update catalog-v001.xml if needed.

  6. Commit the change to GitHub.
    Use a clear commit message. Include the upstream version you adopted and a one-line summary of any local patches.

Summary

Ontology catalogs let your ontology keep using canonical IRIs while your local tools resolve those IRIs to stable local files. This gives you the best of both approaches: standards-compliant imports in the ontology itself, plus local control over development, testing, and upgrades.

Clone this wiki locally