From e0ced68ef6f807d6bb87d87dd1f280fb73c555c8 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 25 Aug 2026 23:51:06 +0000 Subject: [PATCH] docs(glossary): name the typed metadata artifact in the category's vocabulary MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The README leads with "business ontology" four times; `content/docs/**` contained "ontology" zero times (438 files). Measured both ways with a positive control: `metadata` returns 272 files and `business logic` 26 over the same corpus and the same command shape, and a nonsense token returns 0 — so the zero was the term's genuine absence, not a broken pathspec. The README is not overclaiming. The concept is real and central; the docs simply name it with other words — "typed metadata", "Single Source of Truth", "the app contract", "Protocol Definition". The repo's own ADRs already use "ontology" for exactly this referent (ADR-0063 "the ontology is in the metadata"; ADR-0109 "the platform's ontology is already executable"), and the docs site's landing page carries the claim in its own copy and meta description. So the gap is one missing equivalence statement, not a vocabulary migration. This states it once, in the glossary — the page whose stated job is "the shared vocabulary used across these docs" — and disambiguates it from "semantic layer", which in this corpus already means the narrower analytics `dataset` layer (ADR-0021). No other page changes; no existing wording is rephrased. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UjM2ia8Av1v5NqfqQEQmC6 --- content/docs/getting-started/glossary.mdx | 27 +++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/content/docs/getting-started/glossary.mdx b/content/docs/getting-started/glossary.mdx index a930237548..105b56ebe2 100644 --- a/content/docs/getting-started/glossary.mdx +++ b/content/docs/getting-started/glossary.mdx @@ -80,6 +80,33 @@ Reusable error maps, suggestions, and metadata normalization utilities. ## Architecture Concepts +### Business Ontology +The enterprise-AI category's name for the thing these docs otherwise call **typed +metadata**, the **single source of truth**, or the **app contract**: one machine-readable +definition of a business domain — its objects and fields, the relations between them, the +permissions that govern them, and the flows and actions that operate on them. If you +arrived from that vocabulary, this is the term's referent here: the **Source** you author +(`objectstack.config.ts`) and the **Artifact** it compiles to (`objectstack.json`), from +which the runtime derives the database schema, REST API, UI, and MCP server. See +[Metadata-Driven Development](/docs/concepts/metadata-driven). + +The word is worth stating explicitly because ObjectStack's differs from the hosted +ontologies the category otherwise means by it, on two points: + +* **You own the definition.** It lives in your repository as ordinary TypeScript, + versioned in your VCS and reviewable as a diff, in a format specified and licensed + Apache-2.0 — not as a graph held inside a vendor's system and reachable only through + that vendor's console. +* **It is executed, not merely described.** The same definition is enforced at authoring + time by Zod schemas and the validation gate, and at runtime on every call — RBAC, FLS, + and audit included (see **Agent-Ready Boundaries** below). It is not a descriptive map + of behaviour implemented somewhere else, so it cannot drift from the system it + describes. + +Distinct from **semantic layer**, which in these docs means the narrower analytics +`dataset` layer (ADR-0021) that reports and dashboards bind to — see +[Analytics & Datasets](/docs/data-modeling/analytics). + ### Protocol-Driven 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).