Skip to content

Commit 619ea3b

Browse files
claudeclaude
committed
docs(concepts): add the Business Ontology page; landing paragraph and glossary bridge to it
content/docs/concepts/ontology.mdx is the authority on what "business ontology" means here: the core (objects and fields, relations, actions, permissions, flows, agent and tool definitions), the projections (views, dashboards, apps, translations), what it is not (a knowledge ontology with inheritance, axioms and a reasoner; the industry's read-only semantic layer; a philosophical ontology), how the runtime derives and enforces it, and how AI writes and operates it. Registered in the concepts meta.json after metadata-driven. The docs landing page opens on the slogan and descriptor and links the page; the glossary's Business Ontology entry shrinks to a six-line definition plus the link, with the semantic-layer distinction beside the existing analytics-dataset sentence. Claude-Session: https://claude.ai/code/session_011hRnra93sK5Q2gTYYTbdJR Co-authored-by: Claude <noreply@anthropic.com>
1 parent 7396321 commit 619ea3b

4 files changed

Lines changed: 117 additions & 53 deletions

File tree

‎content/docs/concepts/meta.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
"pages": [
44
"architecture",
55
"metadata-driven",
6+
"ontology",
67
"metadata-lifecycle",
78
"design-principles",
89
"north-star"

‎content/docs/concepts/ontology.mdx‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
title: Business ontology — the executable definition the runtime runs
3+
navTitle: Business Ontology
4+
description: "What ObjectStack means by business ontology: the executable definition the runtime runs, its projections, what it is not, and how AI writes and uses it."
5+
---
6+
7+
**The ontology is the software.** One executable business ontology. AI writes it, the
8+
runtime runs it, agents operate it, you own it. This page is the authority on what that
9+
word means here; the [glossary entry](/docs/getting-started/glossary#business-ontology)
10+
is the short form.
11+
12+
## What the ontology is
13+
14+
The ontology is the definition of your business that the runtime executes: authored as
15+
typed metadata in `objectstack.config.ts`, compiled into the `objectstack.json` artifact.
16+
Its core is six kinds of thing:
17+
18+
| Core | What it declares |
19+
| :--- | :--- |
20+
| **Objects and fields** | The entities of the business and their typed attributes — validation, formulas, defaults, files |
21+
| **Relations** | Lookups and master-detail links between objects |
22+
| **Actions** | The operations a user or an agent may invoke on a record, and the conditions under which they show |
23+
| **Permissions** | Who may read, create, edit and delete what — RBAC, row-level and field-level security, sharing |
24+
| **Flows** | The business processes — DAG flows, record triggers, scheduled jobs, approvals, workflows |
25+
| **Agent and tool definitions** | The AI agents the app ships with, the tools they may call, and the skills that shape them |
26+
27+
It is one definition, open and versioned. It lives in your repository as ordinary
28+
TypeScript, is reviewable as a diff, and is specified and licensed Apache-2.0 — not a
29+
graph held inside a vendor's system and reachable only through that vendor's console.
30+
The runtime derives everything else from it.
31+
32+
## What the projections are
33+
34+
Views, dashboards, apps, and translations are **projections** of the ontology — authored
35+
in metadata too, validated by the same gate, but not part of the ontology. A list view
36+
projects an object's fields and permissions onto a grid; a dashboard projects queries over
37+
objects onto charts; an app groups objects, views and actions into a navigable product; a
38+
translation projects every label into a locale. Change the core and the projections
39+
follow; remove a projection and the business it showed is unchanged. The distinction
40+
bounds what an agent must hold to reason about the business: the core, not every screen.
41+
42+
## What it is not
43+
44+
- **Not a knowledge ontology.** OWL, RDF and knowledge graphs *describe* a domain, carry
45+
class inheritance and axioms, and are *reasoned over* by an inference engine.
46+
ObjectStack has no object inheritance, no axioms and no reasoner: the definition is
47+
*validated* — by Zod schemas and `os validate` — and then *run*. The `abstract` key was
48+
removed from the spec for exactly that reason (ADR-0049).
49+
- **Not the industry's semantic layer.** A semantic layer is a read-only mapping over
50+
existing systems: it describes the business but does not run it. ObjectStack's ontology
51+
*is* the system — the database, API, UI and agent tools are derived from it. Federating
52+
an external datasource is possible, read-only by default and early; see
53+
[External Datasources](/docs/data-modeling/external-datasources). These docs also use
54+
*semantic layer* in a narrower sense, for the analytics `dataset` layer that reports and
55+
dashboards bind to; see [Analytics & Datasets](/docs/data-modeling/analytics).
56+
- **Not a formal ontology in the philosophical sense.** It makes no claim about what
57+
exists in general. It is one business's application, defined precisely enough to run.
58+
59+
## How the runtime executes it
60+
61+
```text
62+
objectstack.config.ts -> objectstack.json -> ObjectStack runtime -> database · REST / realtime API · UI · MCP server
63+
```
64+
65+
From the compiled artifact the runtime **derives** the database schema on an
66+
interchangeable driver, a generated REST and realtime API, server-driven UI for the
67+
Console, and an MCP server — and it **enforces** the definition on every call. RBAC,
68+
row-level and field-level security, sharing, and audit apply to a REST request, a Console
69+
click and an agent's tool call alike. Nothing is reasoned over at runtime: what runs is
70+
what was validated.
71+
72+
Code does not disappear — it moves into the runtime. Hooks, action bodies, and the CEL
73+
expressions in formulas, predicates and policies run inside the runtime's permission and
74+
audit fence; constrained JSX in pages is parsed into a server-driven UI tree, never
75+
executed as code. None of it is scattered across a codebase the ontology would then have
76+
to describe. [Protocol Architecture](/docs/concepts/architecture) covers the layers;
77+
[Metadata-Driven Development](/docs/concepts/metadata-driven) shows what one definition
78+
derives.
79+
80+
## How AI writes it and uses it
81+
82+
**Writing it.** The scaffolder installs the AI skills bundle and writes an `AGENTS.md`, so
83+
a coding agent starts with the protocol's rules loaded rather than generic priors. The
84+
agent writes the definition as typed metadata; strict TypeScript and Zod reject shape
85+
errors in the editor, and `os validate` rejects metadata that type-checks but would fail
86+
silently at runtime — dangling bindings, bad CEL predicates, a missing security posture —
87+
as located, corrective text the agent reads and fixes itself. You approve a small,
88+
readable diff in the Console. The loop end to end is
89+
[Build with Claude Code](/docs/getting-started/build-with-claude-code); why it is fast
90+
and safe is [How AI Development Works](/docs/getting-started/how-ai-development-works).
91+
92+
**Using it.** The running app is an MCP server, on by default: every object is a tool,
93+
every exposed action is a tool, permissions decide what an agent may call, and audit
94+
records what it did. An agent operates the app through the same typed, permission-aware
95+
surface as a human — never raw SQL or scraped UI. See
96+
[Connect an MCP Client](/docs/ai/connect-mcp).
97+
98+
Size is what makes both halves work. An app whose definition fits in one context window
99+
is one an agent can read whole, reason about whole, and refactor whole — apps small
100+
enough for AI to hold whole.

‎content/docs/getting-started/glossary.mdx‎

Lines changed: 12 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -82,49 +82,18 @@ Reusable error maps, suggestions, and metadata normalization utilities.
8282
## Architecture Concepts
8383

8484
### Business Ontology
85-
The enterprise-AI category's name for the thing these docs otherwise call **typed
86-
metadata**, the **single source of truth**, or the **app contract**: one machine-readable
87-
definition of a business domain — its objects and fields, the relations between them, the
88-
permissions that govern them, and the flows and actions that operate on them. If you
89-
arrived from that vocabulary, this is the term's referent here: the **Source** you author
90-
(`objectstack.config.ts`) and the **Artifact** it compiles to (`objectstack.json`), from
91-
which the runtime derives the database schema, REST API, UI, and MCP server. See
92-
[Metadata-Driven Development](/docs/concepts/metadata-driven).
93-
94-
The slogan this reduces to is **the ontology is the software**, and the word is worth
95-
stating explicitly because ObjectStack's differs from what the term otherwise means, in
96-
two directions.
97-
98-
**Against a knowledge ontology** (OWL, RDF, a knowledge graph): a knowledge ontology
99-
*describes* a domain, is read-only to the systems that consult it, and is *reasoned over*
100-
by an inference engine. An executable ontology *defines* the app, is *run* by the
101-
runtime, and is *validated* rather than reasoned. ObjectStack has no object inheritance,
102-
no axioms and no reasoner (the `abstract` key was removed from the spec for exactly that
103-
reason, ADR-0049), and it is not a semantic layer over your existing systems —
104-
federating an external datasource is read-only by default and early (see
105-
[External Datasources](/docs/data-modeling/external-datasources)).
106-
107-
**Against a hosted ontology** (a graph held inside a vendor's system), on two points:
108-
109-
* **You own the definition.** It lives in your repository as ordinary TypeScript,
110-
versioned in your VCS and reviewable as a diff, in a format specified and licensed
111-
Apache-2.0 — not as a graph held inside a vendor's system and reachable only through
112-
that vendor's console.
113-
* **It is executed, not merely described.** The same definition is enforced at authoring
114-
time by Zod schemas and the validation gate, and at runtime on every call — RBAC, FLS,
115-
and audit included (see **Agent-Ready Boundaries** below). It is not a descriptive map
116-
of behaviour implemented somewhere else, so it cannot drift from the system it
117-
describes.
118-
119-
**Core and projections.** The ontology core is objects, relations, actions,
120-
permissions, flows, and agent and tool definitions. Views, dashboards, apps, and
121-
translations are *projections* of that core — authored in metadata too, but not
122-
ontology. And code does not disappear: it moves into the runtime, as hooks, action
123-
bodies, CEL expressions, and constrained JSX.
124-
125-
Distinct from **semantic layer**, which in these docs means the narrower analytics
126-
`dataset` layer (ADR-0021) that reports and dashboards bind to — see
127-
[Analytics & Datasets](/docs/data-modeling/analytics).
85+
One executable definition of a business — its objects and fields, relations, actions,
86+
permissions, flows, and agent and tool definitions — that the runtime runs: the **Source**
87+
you author (`objectstack.config.ts`) and the **Artifact** it compiles to (`objectstack.json`).
88+
Views, dashboards, apps, and translations are projections of it, not part of it; code does
89+
not disappear, it moves into the runtime. The slogan this reduces to is **the ontology is
90+
the software** — the full account is [Business Ontology](/docs/concepts/ontology).
91+
92+
It is executable, not a knowledge ontology: no object inheritance, no axioms, no reasoner.
93+
Not the industry's **semantic layer** either — a read-only mapping over existing systems
94+
that describes the business but does not run it. Distinct too from **semantic layer** in
95+
these docs' narrower sense, the analytics `dataset` layer (ADR-0021) that reports and
96+
dashboards bind to — see [Analytics & Datasets](/docs/data-modeling/analytics).
12897

12998
### Protocol-Driven
13099
A development paradigm where logic is defined in static, declarative data formats (JSON/YAML) with Zod schemas rather than imperative code. The goal is to separate the **Intent** (Business Logic) from the **Implementation** (Tech Stack).

‎content/docs/index.mdx‎

Lines changed: 4 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,13 @@
11
---
22
title: Documentation — build apps from metadata
3-
description: "ObjectStack documentation: build business apps from typed metadata that AI agents write and humans verify — start here for guides, concepts and APIs."
3+
description: "ObjectStack documentation: one executable business ontology — AI writes it, the runtime runs it, agents operate it, you own it. Start here for guides, concepts and APIs."
44
---
55

66
## ObjectStack Documentation
77

8-
ObjectStack is an **AI-native business backend protocol** for structured, auditable
9-
business applications. The way you build it: **an AI agent (Claude Code) authors your
10-
application as typed metadata — data model, logic, permissions, UI — a validation gate
11-
rejects mistakes that would fail silently at runtime, and you verify the result in a
12-
visual Console.** From that one source of truth the runtime derives everything else — the
13-
database schema on interchangeable drivers, a generated REST + realtime API,
14-
permission-checked automation, server-driven UI, and an **MCP server**, so the app you
15-
build is itself AI-operable. Agents act through the same typed, permission-aware surface —
16-
never raw SQL or scraped UI.
8+
**The ontology is the software.** One executable business ontology. AI writes it, the
9+
runtime runs it, agents operate it, you own it. What the word means here — and what it
10+
does not — is [Business Ontology](/docs/concepts/ontology).
1711

1812
```mermaid
1913
flowchart LR

0 commit comments

Comments
 (0)