ONTOLOGIES

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

FieldRequiredTypeRules
nameyesstringLowercase 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.
descriptionyesstringOne or two sentences, at most 280 characters. Shown on catalogue cards and in search.
licenseyesstringAn 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.
entitiesyeslist of stringsThe 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.
formatsnolist of stringsFile formats included, as lowercase extensions without the dot (pg, ttl, owl, jsonld, yaml, sql). If missing, the site works it out from the files.
upstreamnoURLWhere the canonical source lives, when this ontology is a copy or a subset of one.
tagsnolist of stringsUp to 10, each lowercase, hyphenated, at most 32 characters. Used for search.
canonicalnopathThe 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.
versionnostringInformational 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:

  1. What it models. Two to five sentences on the domain and where it stops.
  2. Entities. Each main type: what it is and its key properties.
  3. Relations. One line each, as Source → relation → Target, with cardinality in brackets when it matters: [0..1], [1], [0..*], [1..*]. For example Deal → DealWith → Organization [1]. Optionally follow the list with a diagram (see §3.1).
  4. Modeling decisions. Why it's shaped this way, what you left out, and what you'd do differently.
  5. 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.
  6. 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 classDef colours if the ontology has them.
  • Only the first mermaid block counts. ontology init drafts one from .pg and 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

AddressMeaning
owner/repoThe 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/nameThe ontology in the repo whose frontmatter name is name.
…@refA 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, and LICENSE, 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.

  1. Push a public GitHub repo with a valid ONTOLOGY.md.
  2. 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.