---
title: Ontology
description: "Semantic model, stable category codes, counterparties, and agent categorization rules."
canonical: https://bennybooks.com/developers/reference/ontology
markdown: https://bennybooks.com/developers/reference/ontology.md
---
# Ontology

Semantic model, stable category codes, counterparties, and agent categorization rules.

> **Documentation index.** Fetch [https://bennybooks.com/developers/llms.txt](https://bennybooks.com/developers/llms.txt) before browsing further. Prefer markdown (this file or `Accept: text/markdown`). Site-wide map: [https://bennybooks.com/llms.txt](https://bennybooks.com/llms.txt).

BennyBooks uses a lightweight ontology so agents categorize by stable codes (5100) instead of ambiguous display names (Software vs Software & tools). Postgres remains the source of truth; JSON-LD / Turtle describe meaning.

> **Preferred agent flow.** GET /categories → match description to counterparties/synonyms → POST /proposals/categorization with categoryCode + confidence + reason (+ evidence). Humans approve in Ledger → Approvals; the trail lives in Log (https://bennybooks.com/log).

## Public endpoints

```text Ontology (JSON-LD)
https://bennybooks.com/api/v1/ontology.jsonld
```

```text Ontology (Turtle)
https://bennybooks.com/api/v1/ontology.ttl
```

```text JSON-LD context
https://bennybooks.com/api/v1/ontology/context.jsonld
```

```text SPARQL (static ontology only)
https://bennybooks.com/api/v1/ontology/sparql
```

No authentication required. SPARQL is query-only over the static ontology graph — it does not return org ledger data. Prefer get_ontology or list_categories for typical agent workflows. OpenAPI also lists get_ontology_ttl and sparql_ontology (off by default for MCP bridges).

```bash Example SPARQL
curl -sG "https://bennybooks.com/api/v1/ontology/sparql" \
  --data-urlencode 'query=PREFIX bb: <https://bennybooks.app/ontology#>
SELECT ?code ?name WHERE {
  ?c a bb:Category ; bb:categoryCode ?code ; bb:categoryName ?name .
} ORDER BY ?code'
```

## Core classes

| Class | Purpose |
| --- | --- |
| Transaction | Money movement (negative amount = outflow) |
| Category | Chart-of-accounts slot — identify by code |
| Counterparty | Vendor/customer with aliases (seed list today; DB planned) |
| Receipt | Evidence document |
| Note | Free-text annotation |
| Proposal | Agent suggestion awaiting approval |
| Audit log entry | Agent write or human review event (Log UI) |
| Connector | Bank/payment data source |

## Default chart codes

| Code | Name | Type | Synonyms |
| --- | --- | --- | --- |
| 5100 | Software & tools | expense | Software, SaaS, Subscriptions |
| 5200 | Office & rent | expense | Rent, Coworking, WeWork |
| 5300 | Cloud infrastructure | expense | Cloud, AWS, GCP, Azure |
| 5000 | Operating expenses | expense | Travel, Contractors, Professional services |
| 4000 | Revenue | revenue |  |
| 4010 | SaaS subscriptions | revenue |  |

## Seed counterparties

| Vendor | Default code | Aliases |
| --- | --- | --- |
| AWS | 5300 | Amazon Web Services, AMZN AWS |
| Figma | 5100 | FIGMA INC |
| Google Workspace | 5100 | Google Cloud |
| Stripe | 4000 | STRIPE PAYOUT |
| WeWork | 5200 |  |

## Propose with categoryCode

```json POST https://bennybooks.com/api/v1/proposals/categorization
{
  "transactionId": "550e8400-e29b-41d4-a716-446655440000",
  "categoryCode": "5300",
  "confidence": 0.91,
  "reason": "Description matches counterparty AWS",
  "evidence": [
    { "type": "counterparty_match", "value": "aws" }
  ]
}
```

> category (name) still works for compatibility. Prefer categoryCode. The API resolves codes to the canonical chart name stored on the transaction today.

Full reference: docs/ONTOLOGY.md. Source files: ontology/bennybooks.jsonld and ontology/bennybooks.ttl.

---

## Machine-readable

- HTML: https://bennybooks.com/developers/reference/ontology
- Markdown: https://bennybooks.com/developers/reference/ontology.md
- Docs index: https://bennybooks.com/developers/llms.txt
- OpenAPI: https://bennybooks.com/openapi.json
- Skill: https://bennybooks.com/skill.md
- Auth: https://bennybooks.com/auth.md

```json
{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "Ontology",
  "description": "Semantic model, stable category codes, counterparties, and agent categorization rules.",
  "url": "https://bennybooks.com/developers/reference/ontology",
  "inLanguage": "en",
  "encodingFormat": [
    "text/html",
    "text/markdown"
  ],
  "isAccessibleForFree": true,
  "publisher": {
    "@type": "Organization",
    "name": "BennyBooks",
    "url": "https://bennybooks.com",
    "logo": {
      "@type": "ImageObject",
      "url": "https://bennybooks.com/apple-icon.png"
    }
  },
  "mainEntityOfPage": "https://bennybooks.com/developers/reference/ontology",
  "image": "https://bennybooks.com/opengraph-image",
  "workExample": {
    "@type": "CreativeWork",
    "url": "https://bennybooks.com/developers/reference/ontology.md",
    "encodingFormat": "text/markdown",
    "name": "Ontology (Markdown)"
  },
  "about": {
    "@type": "WebAPI",
    "name": "BennyBooks Agent API",
    "url": "https://bennybooks.com/api/v1",
    "documentation": "https://bennybooks.com/developers"
  }
}
```
