The ONTOLOGY.md format
Version 0.1 · Draft
An ontology on ontology.sh is a folder with an ONTOLOGY.md file in it. The file describes the things in a domain and how they relate, in plain language, for people and their coding agents. Next to it you can put source files in any format: Omnigraph .pg, Turtle .ttl, OWL .owl, LinkML .yaml, JSON Schema, SQL. None are required.
Someone installs your ontology with:
npx ontology.sh add <owner>/<repo>[/<name>][@<ref>]
This copies your folder into their project. Their agent then reads your ONTOLOGY.md and fits the ontology into their own schema. Write it for that reader.
1. The file
ONTOLOGY.md is UTF-8 Markdown that starts with YAML frontmatter between --- lines. It can be up to 256 KB.
---
name: prov-o
description: How data came to be. Entities, the activities that produced them, and the agents responsible.
license: W3C-20150513
entities: [Entity, Activity, Agent]
formats: [ttl, owl]
upstream: https://www.w3.org/TR/prov-o/
tags: [provenance, w3c]
version: 0.1.0
---
# PROV-O
## What it models
...
2. Frontmatter
| Field | Required | Type | Rules |
|---|---|---|---|
name | yes | string | Lowercase letters, digits and single hyphens; starts with a letter; at most 64 characters. Unique within the repo. It becomes the install folder name and the last part of the address. |
description | yes | string | One or two sentences, at most 280 characters. Shown on catalogue cards and in search. |
license | yes | string | An SPDX identifier such as MIT, CC-BY-4.0, CC-BY-SA-3.0, W3C-20150513, or the word proprietary. If you derived the ontology from someone else's, use their license. |
entities | yes | list of strings | The main types, 1 to 50, each 1 to 64 characters, no duplicates. Shown on cards and in the diagram. List the types a reader needs to know, not every class. |
formats | no | list of strings | File formats included, as lowercase extensions without the dot (pg, ttl, owl, jsonld, yaml, sql). If missing, the site works it out from the files. |
upstream | no | URL | Where the canonical source lives, when this ontology is a copy or a subset of one. |
tags | no | list of strings | Up to 10, each lowercase, hyphenated, at most 32 characters. Used for search. |
canonical | no | path | The one source file the others are derived from, relative to the folder (base.pg). Set it when the folder holds the same schema in several formats. It must be one of the files in the folder, and one that gets copied (§6); otherwise add and the catalogue refuse the ontology. |
version | no | string | Informational only. The git ref is what pins an install. An unquoted number such as 0.99 is read as the string "0.99". |
Other fields are allowed and ignored, so you can add your own.
3. Body
The body is free Markdown. These sections are recommended, in this order, because the ontologies agent skill looks for them:
- What it models. Two to five sentences on the domain and where it stops.
- Entities. Each main type: what it is and its key properties.
- Relations. One line each, as
Source → relation → Target, with cardinality in brackets when it matters:[0..1],[1],[0..*],[1..*]. For exampleDeal → DealWith → Organization [1]. Optionally follow the list with a diagram (see §3.1). - Modeling decisions. Why it's shaped this way, what you left out, and what you'd do differently.
- How to integrate. Overlaps to expect with common schemas (for example "Agent overlaps Person and Organization"), and what is lost when translating to other formats.
- Files. What each source file is.
3.1 The diagram
Put one Mermaid flowchart LR block in the Relations section. GitHub renders it, agents read it, and ontology.sh shows it on the package page. It's optional: without it, the site draws the entities list.
```mermaid
flowchart LR
classDef people fill:#e8f0fe,stroke:#4a6fd1
Person["<b>Person</b>"]:::people
Team["<b>Team</b><br/><small>↻ part of</small>"]:::people
Decision["<b>Decision</b><br/><small>↻ superseded by</small>"]
Person -->|"member of"| Team
Decision -->|"decided by (1)"| Person
```
- One node per entity, labelled
<b>Name</b>. - Edges are relations, labelled in plain words, with cardinality in brackets when it matters.
- A relation from a type to itself goes in the node label as
<small>↻ relation</small>, not as a looping edge. - Group layers with
classDefcolours if the ontology has them. - Only the first
mermaidblock counts.ontology initdrafts one from.pgand Turtle sources.
A body under 20 lines is valid but rarely useful. A good ONTOLOGY.md lets an agent integrate the ontology without opening the source files.
3.2 One schema, several formats
An ontology can ship the same schema in more than one format, so people can drop it into the stack they already use: Omnigraph .pg, Cypher constraints for Neo4j, a GraphQL schema, Atlas HCL for SQL databases, Turtle or OWL.
- One file is canonical. Name it in
canonical. It's the one you edit; the rest are generated from it. - Derived files say so. Start each one with a comment naming its source, such as
# Generated from base.pg. Edit base.pg and regenerate. - Use the common extensions and list them in
formats:pg,cypher,graphql,hcl,ttl,owl,rdf,jsonld,sql. - Say what each translation loses in the Files section. Cypher has no relationship schema and enforces existence and types only in Neo4j Enterprise; SQL turns edges into foreign keys or join tables; GraphQL has no keys or uniqueness.
- Load them into the real thing. Apply each derived file to the database it targets, twice (the second run should change nothing), and try a few inserts that must be refused: a missing required field, a wrong type, a duplicate key.
You don't have to write the derived files by hand: the ontologies agent skill can generate them from the canonical file. The modernrelay/ontologies seed ships base and company-brain this way, as templates, checked on Neo4j 5 and PostgreSQL 16.
4. Addresses
| Address | Meaning |
|---|---|
owner/repo | The ontology whose ONTOLOGY.md is at the repo root. If the root has none and the repo holds several, the CLI asks which one. |
owner/repo/name | The ontology in the repo whose frontmatter name is name. |
…@ref | A tag, branch or commit. Without it, the default branch. |
owner and repo are the GitHub path, so nobody can take a name that belongs to someone else.
On the site, an ontology at the repo root is listed as owner/repo, and one in a subfolder as owner/repo/name.
5. Several ontologies in one repo
Put each in its own folder with its own ONTOLOGY.md:
my-ontologies/
README.md
crm/
ONTOLOGY.md
crm.pg
billing/
ONTOLOGY.md
billing.ttl
The CLI looks for ONTOLOGY.md files up to three folders deep. It skips node_modules, .git and folders whose names start with a dot. Each name must be unique in the repo. A root ONTOLOGY.md makes the repo a single-ontology repo, and subfolders are then ignored.
6. What gets copied
The folder that contains ONTOLOGY.md lands in the installer's project at ontologies/<owner>/<name>/, with a .source.json file added that records where it came from.
Only schema, data, docs and image files are copied, so nothing executable ends up in someone else's project:
- Docs:
.md,.txt, andLICENSE,README,NOTICE,COPYING,AUTHORS. - Schemas and data:
.pg,.ttl,.owl,.rdf,.jsonld,.json,.nt,.nq,.trig,.n3,.obo,.xsd,.shacl,.cypher,.cql,.graphql,.gql,.hcl,.sql,.yaml,.yml,.csv,.tsv,.mmd. - Images:
.png,.jpg,.jpeg,.gif,.svg,.webp.
Everything else stays behind: scripts, package manifests (package.json and lock files), dot-files and node_modules. add lists what it skipped.
7. Publishing
There is no publish step and no sign-up.
- Push a public GitHub repo with a valid
ONTOLOGY.md. - Install it once:
npx ontology.sh add you/your-repo.
The install registers it, and it appears in the catalogue. Installs are counted anonymously; the catalogue is ranked by them.
8. Validation
The CLI, the site and the registry all run the same validator. A file is valid when:
- it starts with
---, has a closing---, and the frontmatter between them is a YAML mapping; - every required field is present and follows the rules in §2;
- the body after the frontmatter is not empty.
An invalid ONTOLOGY.md is never installed and never listed. The error names every problem, not just the first.