ELOT

May 8, 2026 · View on GitHub

A single plain-text document that is simultaneously your ontology source, its documentation, its query workspace, and its diagram generator.

VS Code Extension — Now on the Marketplace

ELOT is no longer Emacs-only. The Elot VS Code extension brings literate ontology editing to Visual Studio Code, with full support for Org-mode ontology files.

Install it now from the Visual Studio Marketplace — or search for "Elot" in the VS Code Extensions panel.

The extension provides:

Org→OWL pipeline — Generate OWL Manchester Syntax directly from Org-mode files (powered by orgize, a Rust Org parser compiled to WASM)
Label Display — Hover over CURIEs to see labels and annotations; press F5 to visually replace identifiers with human-readable labels
Headline Folding — Click the gutter chevrons or press Tab to fold/unfold headings, just like Emacs Org-mode
Go to Definition — Ctrl+Click or F12 on any CURIE to jump to the heading where that entity is declared
Org Indent Mode — Toggle visual indentation (Ctrl+Shift+I) that mimics Emacs's org-indent-mode
IntelliSense Completion — Press Ctrl+Space for a dropdown of all OWL entities in the file, searchable by label or CURIE
Bold Headlines & Description List Fontification — Always-on visual enhancements for readability
HTML Export — Generate styled HTML documentation via Pandoc, with clickable CURIE links and section numbering

See the full extension README for keybindings, settings, and screenshots.

Importing existing OWL ontologies into VS Code

Have an existing ontology? The Elot extension can import it directly:

Open the Command Palette (Ctrl+Shift+P) and run Elot: Import OWL Ontology
Choose a local file or paste a URL (e.g. from a published ontology IRI)
The extension downloads elot-exporter.jar automatically (requires Java 21+ on PATH) and converts the OWL file into Elot's Org-mode format
You are prompted to save the resulting .org file — once saved, all Elot features activate immediately

You can also use the CLI directly:

node dist/cli.js input-ontology.owl -o output.org

Why ELOT?

Ontology engineering today is fragmented across disconnected tools: you author in Protégé, generate documentation with WIDOCO or PyLODE, visualize in WebVOWL, and manage versions in Git — each tool speaking its own language. This fragmentation creates friction, makes it hard to keep documentation and formalization in sync, and discourages prose justification of design decisions.

ELOT introduces literate ontology engineering: a workflow, inspired by Knuth's literate programming tradition, in which a single Org Mode plain-text file is the authoritative source for everything. Headlines are the taxonomy; description lists are the axioms and annotations. Documentation is not generated after the fact from rdfs:comment fields — it lives alongside the formal content, and HTML or PDF export captures both. SPARQL queries and rdfpuml diagrams execute in place, so the document is also an analytical workspace. Because the source is plain text, ontology changes produce clean, human-readable diffs; and because it is plain text, it is naturally consumable by LLMs for AI-assisted authoring.

This approach has real-world validation: ELOT has been used across scores of ontology projects, including the ISO 23726-3 Industrial Data Ontology. In collaborative standards work, having a single source for ontology and documentation is a decisive practical advantage.

What's New in 2026

Global label-display mode — A new minor mode, elot-global-label-display-mode, brings ELOT's readable-label overlays to any buffer: Turtle files, SPARQL queries, CSV data, source code, log files. Labels are drawn from a persistent SQLite index (elot-db) that is populated automatically and silently as you work in ELOT Org files — every ontology you open or save contributes its id/label mappings to the database, so they are available across sessions and across buffers. A scope-aware elot-label-lookup command (C-c C-x r) offers completion over both the current buffer's ontology and everything the DB knows about, with two-stage disambiguation when many identifiers share a label (common in industrial asset data). Attribute-driven eldoc and lazy help-echo surface rdf:type, definitions, and source provenance on hover. BCP-47 language tags are respected via elot-preferred-languages (default: untagged, then @en, then alphabetical). See README-global-label-display.org for details.
VS Code extension on the Marketplace — Install from marketplace.visualstudio.com. ELOT is now accessible to any developer with VS Code — no Emacs required. Features include label display, headline folding, go-to-definition, org-indent mode, IntelliSense, and bold/fontified headings.
v2.0 refactoring — Ontology content is now derived directly from Org headlines and description lists; no more boilerplate org-babel source blocks required. Parsing is cleaner, significantly more efficient on large files, and supports multiple ontologies per file.
elot-exporter (Java/OWLAPI) — Comprehensive OWL→Org conversion with checksum protection and Manchester Syntax rendering. Import any existing ontology and continue working in ELOT. Download from releases; source in tools/elot-exporter/.
elot-cli (TypeScript/WASM) — An editor-independent Org→OWL pipeline built on orgize (Rust) compiled to WASM. Source in tools/elot-cli/.
Round-trip test suite — Systematic validation against real-world ontologies (BFO, Pizza, and others) with automated diffing.

How It Compares

Most ontology tools occupy a single niche: Protégé is an authoring GUI, WIDOCO/PyLODE generate reference documentation, WebVOWL provides interactive visualization, and VoCol supports Git-based collaboration workflows. ELOT is the only tool that spans authoring, documentation generation, integrated SPARQL querying, diagram generation, and VCS-friendly plain-text format in a single workflow — at the cost of a higher initial learning curve. The VS Code extension and elot-cli are progressively lowering that barrier.

Two Ways to Use ELOT

	VS Code	Emacs
Install	VS Code Marketplace	Clone repo + `(require 'elot-mode)`
Org→OWL	✅ Built-in (WASM)	✅ Built-in (Elisp)
Label display	✅ F5 toggle	✅ Menu / opt-in F5
Folding	✅ Tab / gutter	✅ Native Org cycling
Go to definition	✅ F12 / Ctrl+Click	✅ M-. (xref)
IntelliSense	✅ Ctrl+Space	✅ `completing-read`
SPARQL queries	— (planned)	✅ `org-babel`
Diagrams	— (planned)	✅ rdfpuml integration
HTML export	✅ Built-in (Pandoc)	✅ `org-export`

Getting Started with VS Code

Install the extension from the Visual Studio Marketplace
Open an .org ontology file — try the examples in tools/elot-cli/examples/
Hover over a CURIE to see labels and annotations
Press F5 to toggle visual label display
Press Tab on a heading to fold/unfold
Press F12 on a CURIE to jump to its definition
Press Ctrl+Space to search and insert entities

To import an existing OWL file, use the Elot: Import OWL Ontology command — the extension downloads elot-exporter automatically. Requires Java 21+ (see the Install ELOT auxiliaries section for details).

Prerequisites in brief

Download ELOT using Git to easily obtain updates
Use a recent version (29+) of Emacs
For viewing your ontologies, install Protégé Desktop
Install Java to enable advanced features
- Turtle output, ontology metrics, and more: install ROBOT
- Ontology diagrams: install PlantUML and rdfpuml
- Open OWL files: Download elot-exporter from releases
- Java 21 or newer is required for elot-exporter. Many enterprise laptops ship with an older Java (8, 11, or 17); check with java -version and upgrade if needed. Running the jar on an older JRE fails with UnsupportedClassVersionError. See the elot-exporter notes below.

Installation

Get Emacs

See the GNU Emacs download page.

For new Windows users: download Emacs from a GNU mirror; the latest version is in the emacs-30 directory. The package named emacs-30.1-installer.exe will work fine (as of 2025-03-11). It's preferable to install into a folder that doesn't contain spaces.

If you are new to Emacs, the book Mastering Emacs is highly recommended.

Install ELOT in Emacs

ELOT is in active development. For easy access to updates, you should clone the ELOT repository using Git.

Create a directory for local Emacs add-ons in your home folder, named elisp (on Windows, that will likely mean c:\Users\mynamelisp\).
Clone ELOT into the elisp folder using your Git client. If using a terminal for Git, the following will do it.
```
cd elisp
git clone https://github.com/johanwk/elot.git
```
You should now have a subfolder of elisp called elot.
Ensure ELOT is loaded when Emacs starts up.
- For new Emacs users: find the file elot-init.el inside the elot folder, and copy its contents to your .emacs file (typically found in your home folder), then restart Emacs. You should now have a basic, working Emacs configuration that automatically activates elot-mode when you open an ontology file.
- Experienced Emacs users should add ~/elisp/elot/elot-package/ to their load-path and (require 'elot-mode).

Install ELOT auxiliaries

ELOT relies on external software programs to query your ontologies and produce diagrams. These need to be downloaded.

Preparatory steps, if needed:

Create a directory named bin in your home folder: you will download programs to this folder. On Windows, that will mean c:\Users\mynamein\; also ensure the environment variable HOME is set (check issue 83).
Ensure the bin folder is on your PATH, so the programs can be found by ELOT. On Windows, use the Control Panel to edit Local Environment Variables and add c:\Users\mynamein\ to the list.

Get the tools:

The ROBOT tool is highly recommended for ELOT. Download robot.jar from the ROBOT releases page to your bin folder.
The PlantUML tool is needed for diagrams. Download the latest version from PlantUML Downloads (tested with plantuml-1.2024.3.jar) to your bin folder. For convenience, rename it as just plantuml.jar (on Linux, make a symlink).
The rdfpuml tool will produce great-looking diagrams for ontologies.
- On Windows, download rdfpuml.exe to your bin folder.
- On Linux or MacOS, clone the repository to your bin folder, then add ~/bin/rdf2rml/bin/ to your PATH. Install Perl modules as listed in the rdfpuml installation guide.
```
cd ~/bin
git clone https://github.com/VladimirAlexiev/rdf2rml.git
```
The elot-exporter tool converts existing OWL ontologies to ELOT's org-mode format. Once downloaded, you can open an OWL ontology from a local file, or from a URL, with M-x elot-open-owl.
- download the latest Java JAR from releases and save it as elot-exporter.jar in your bin folder.
- the source code is available in tools/elot-exporter/ in this repository.
- Requires Java 21 or newer. The jar is compiled against Java 21 (see <release>21</release> in tools/elot-exporter/pom.xml). Many enterprise laptops are provisioned with an older Java (8, 11, or 17); running the jar on those will fail with UnsupportedClassVersionError: ... class file version 65.0 (65 is the class-file major version emitted by Java 21).
  - Check your version: java -version.
  - If it reports 20 or lower, install a current JDK or JRE — for example Eclipse Temurin 21+, Microsoft Build of OpenJDK 21, or Oracle JDK 21+.
  - If your organisation pins an older system Java, you can install a newer JDK alongside it and point ELOT at it via JAVA_HOME or by invoking the jar with an explicit path to the Java 21+ launcher.
  - ROBOT and PlantUML are less demanding (both run on Java 11+), so upgrading to Java 21 for elot-exporter is safe for the other ELOT auxiliaries as well.

Quick start using ELOT

Video.webm

Adding an ontology

Open the familiar Pizza ontology from elisp/elot/examples/pizza.org for an example of what an ELOT file will look like. Check the menu bar to locate the ELOT menu.

To create a new ontology, do this in Emacs:

Select a directory that you want to work in. Open a new Org Mode file, for instance myontology.org.
Insert the ELOT template for a document header. From the bottom of the ELOT menu, select Insert New Ontology Document Header. Answer the prompts, and a header is produced, like the following.
```
#+title: My new ontology
#+subtitle: An OWL ontology
#+author: John Doe
#+date: WIP (version of 2024-04-04 12:34)
```
Insert the ELOT template for an ontology skeleton: menu entry Insert New Ontology Skeleton. Answer the prompts — be ready to provide namespaces/prefixes for your ontology and the resources it will contain. You should see something like this screenshot:

Now create an OWL file from your new document.

Menu entry Export to OWL will "tangle" the ontology to a file in OWL Manchester Syntax, e.g., with filename myontology.omn.
If you have installed ROBOT, a Turtle file named myontology.ttl will also be generated.
Have Protégé ready, and open the ontology file to inspect it.

Export to an HTML document with menu entry Export to HTML. The document will open in your web browser.

Adding classes and relations

Navigate to the Classes heading
Select Insert Primitive/Defined Class template from the menu to declare a class. Some appropriate annotation properties from the Industrial Ontology Foundry Annotation Vocabulary (IOF-AV) are included.
Navigate to the Object properties heading
Select Insert Property template for an object, data, or annotation property.
The screenshot shows how checkboxes are included for tracking progress. These are completely optional and won't appear in output.

Adding annotations

ELOT makes it easy to add annotations to both annotations and axioms: just put them in a description list ( - term :: value). In this screenshot, two annotations are added to the "transitive" characteristic axiom:

Querying the ontology

Navigate to the Prefixes heading and insert a new heading named "Queries".
Select menu item Insert SPARQL Select Block, then write a query over the ontology.
Hit C-c C-c to run the query.

Making a diagram

A SPARQL construct query will produce Turtle code for a diagram. Select Insert SPARQL Construct Block.
Write a query and hit C-c C-c to run it.

Select Insert RDFPUML Diagram Block.
When prompted, provide the name of the Turtle source (the name of the construct query) and a figure caption.
Place the cursor on the row of the #+call: and hit C-c C-c. A diagram is generated.

Select Export to HTML to view your ontology in a browser.

Display labels instead of identifiers

ELOT can display readable labels instead of prefixed identifiers (which are unreadable if the identifiers are not informative), and offers quick search across the ontology resources. Toggle from the ELOT menu or with M-x elot-toggle-label-display.

ELOT does not claim a default keystroke for the toggle (single function keys F5–F9 and C-c <letter> are reserved for the user). To get a quick keybinding, customize elot-toggle-labels-key (M-x customize-variable RET elot-toggle-labels-key) to a kbd-notation string of your choice — for example <f5>, <f9>, or C-c t l. When set, ELOT installs the binding in elot-mode-map and in the ELOT-managed *xref* / *ELOT Describe* buffers.

Global label-display: labels everywhere, automatically

ELOT's label-display is no longer confined to Org buffers. The minor mode elot-global-label-display-mode lights up readable labels in any buffer — .ttl files, SPARQL queries, CSV exports, even source code and log files that mention ontology identifiers. Toggle from the ELOT menu or via M-x elot-toggle-label-display (or your chosen keystroke if you set one — see elot-toggle-labels-key).

The feature that makes this practical in daily work: id/label mappings are collected silently and automatically as you edit ELOT Org files. Every ontology you open, tangle, or save contributes its declarations to a persistent SQLite index (elot-db) that lives across sessions. The more ontologies you touch, the richer the index becomes — with no explicit import step, no manual curation, and no rebuild when you come back tomorrow. Additional sources (TTL via ROBOT, SPARQL endpoints, CSV/TSV/JSON exports) can be registered per-buffer via .dir-locals.el.

Beyond the visual overlays, the mode provides:

elot-label-lookup (C-c C-x r) — Insert an existing resource identifier by searching on its label. Scope is configurable (current buffer only, external sources only, or a union of both). When many identifiers share a label — common in industrial asset data — a two-stage picker lets you drill down with full attribute context.
Attribute-driven hover — Idle the cursor on any identifier to see its rdf:type, definition, and source provenance in the echo area.
Language preferences — Multi-lingual ontologies (e.g. English + Korean) display the right variant based on elot-preferred-languages; the default policy is untagged first, then @en, then alphabetical.

See README-global-label-display.org for configuration, source registration, and language-preference details.

Supported `#+call:` helpers (Library of Babel)

ELOT ships a small Library of Babel file (elot-package/elot-lob.org) that defines a handful of named source blocks intended to be invoked from your ontology Org files via Org's #+call: syntax. When elot-mode is enabled in a buffer, ELOT automatically ingests the file (via org-babel-lob-ingest) so the helpers below are available without any manual setup — no M-x org-babel-lob-ingest step required.

The supported helpers are:

rdfpuml-block — render a Turtle (or SPARQL CONSTRUCT) source block as an rdfpuml/PlantUML diagram. Takes the name of another named block as its ttlblock argument, plus optional config, add-options, epilogue and format arguments. Produces an image file referenced from the surrounding caption.
kill-prefixes — strip leading @prefix / PREFIX declarations from a Turtle string. Most commonly used as a :post hook on a SPARQL CONSTRUCT block to keep the visible result compact.
robot-metrics — run robot measure on an OMN file and return the resulting table.
robot-sparql-select — run a named SPARQL query through ROBOT against a local OMN file and return the result as an Org table.
theme-readtheorg / theme-elot — expand to the right #+SETUPFILE: line for the bundled HTML themes.
current-date / current-datetime — format the current date/time, useful in pav:lastUpdateOn annotations.

A minimal example, taken from examples/pets.org, showing rdfpuml-block consuming a CONSTRUCT block whose result is also post-processed by kill-prefixes:

#+name: my-construct
#+begin_src sparql :url "my-ont.omn" :format ttl :wrap "src ttl" \
                  :cache yes :post kill-prefixes(data=*this*)
  construct {
    ?class a owl:Class .
    ?subclass rdfs:subClassOf ?class .
  } {
    ?class a owl:Class .
    optional { ?subclass rdfs:subClassOf ?class }
  }
#+end_src

#+name: rdfpuml:my-construct
#+call: rdfpuml-block(ttlblock="my-construct")
#+caption: Animal diagram

Place point on the #+call: line and hit C-c C-c to render the diagram. See examples/pets.org for the complete working file.

Navigating Ontologies with Xref

ELOT supports cross-referencing and navigation using Emacs's built-in xref system. This allows users to find where a resource is used and to jump directly to its definition from anywhere in an ELOT buffer.

To find all references to a CURIE (e.g., :BFO_0000015), place the cursor on it and type M-? (xref-find-references). The *xref* buffer will open and show each occurrence, along with the heading and flattened description list entry for context.

Inside the *xref* buffer:

Press RET to jump to the occurrence.
Move the cursor to any other CURIE and press M-. (xref-find-definitions) to jump to its definition (typically the Org headline where it's declared).

Label overlays are enabled automatically in the *xref* buffer, so identifiers appear with readable labels if available. This makes it easier to explore large ontologies interactively.

This functionality is activated automatically for Org files when elot-mode is active.

HTML style

HTML output from ELOT produces stable anchors for ontology resources, and shows readable labels with internal, clickable links.

Tools

Two command-line tools are included under the tools/ directory:

elot-exporter — A Java CLI (OWLAPI + Maven) that converts existing OWL ontologies into ELOT's Org-mode format, producing a shaded JAR.
elot-cli — A TypeScript CLI and VS Code extension that generates OWL Manchester Syntax and HTML documentation from Org-mode files (uses orgize WASM + esbuild + Pandoc). Also provides a db sub-command (elot-cli db init|register|refresh|list|lookup|attr|remove) that manages the persistent SQLite label index used by the global label-display feature; see the Label Database section in the elot-cli README. Available on the Visual Studio Marketplace.