🧬
ontology
Stanford's 7-step ontology methodology, adapted for TypeScript domain modeling
"An ontology is an explicit specification of a conceptualization." — Thomas R. Gruber, Stanford KSL, 1993
Stop designing types by gut feeling. This skill teaches Stanford's Ontology Development 101 methodology — adapted for TypeScript interfaces, SQL schemas, and Zod validators. It turns unstructured domain knowledge into rigorous, typed data architectures through a systematic 7-step process.
Three theoretical pillars:
| Year | Author | Contribution |
|---|---|---|
| 1993 | Thomas R. Gruber (Stanford KSL) | Defined ontology for CS; proposed the Ontolingua translation architecture and 5 design criteria |
| 2001 | Noy & McGuinness (Stanford SMI) | Systematized Gruber's theory into the 7-step Ontology 101 methodology |
| 2025 | Shen Xin (Enterprise Practice) | Applied ontology methods to enterprise AI systems (Digital Intelligence Triad, ITPAO fractal) |
Every codebase eventually hits these walls:
| # | Problem | Symptom |
|---|---|---|
| 🏚️ | God Interface | types/index.ts has 1000+ lines, 50 optional fields. Every change is a gamble. |
| 🔄 | Repeated Modeling | Same "User" concept defined in TS interfaces, Zod schemas, SQL tables, API responses — all inconsistent. |
| 💥 | Classification Chaos | 10 boolean flags (isAdmin, isPremium, isBanned...) instead of a discriminated union. 2^n states. |
| 😰 | Refactoring Fear | No systematic framework for deciding extends vs composition vs union. All gut feeling. |
| 📖 | Knowledge Loss | Domain knowledge scattered across code comments and Slack messages. New devs need 3 weeks to onboard. |
The root cause isn't bad code — it's a missing methodology. You wouldn't build a house without blueprints. Why design a type system without a process?
Each step maps directly to TypeScript code artifacts:
┌─────────────────────────────────────────────────────────────────┐
│ Step 1: Determine Domain & Scope │
│ ➜ Competency Questions → Acceptance Criteria │
├─────────────────────────────────────────────────────────────────┤
│ Step 2: Consider Reusing Existing Ontologies │
│ ➜ Search existing types, npm packages, industry schemas │
├─────────────────────────────────────────────────────────────────┤
│ Step 3: Enumerate Important Terms │
│ ➜ Nouns → Classes, Adjectives → Properties, Verbs → Methods │
├─────────────────────────────────────────────────────────────────┤
│ Step 4: Define Classes & Hierarchy │
│ ➜ Discriminated unions, is-a relationships, extends │
├─────────────────────────────────────────────────────────────────┤
│ Step 5: Define Properties (Slots) │
│ ➜ Intrinsic vs extrinsic fields, ID references │
├─────────────────────────────────────────────────────────────────┤
│ Step 6: Define Constraints (Facets) │
│ ➜ TypeScript types + Zod schemas + SQL constraints (3-layer) │
├─────────────────────────────────────────────────────────────────┤
│ Step 7: Create Instances │
│ ➜ const data arrays, seed data — validate the model works │
└─────────────────────────────────────────────────────────────────┘
claw install ontology-skillgit clone https://github.com/leofankm/claude-ontology-skill
cp -r claude-ontology-skill/skills/ontology ~/.claude/skills/Copy the contents of skills/ontology/SKILL.md into ~/.claude/skills/ontology/SKILL.md.
The skill auto-triggers on keywords like "design a data model", "define types for", "build a taxonomy", "refactor god interface". You can also invoke manually:
/ontology # Show overview and available commands
/ontology analyze src/types/ # Audit existing type system
/ontology design "e-commerce" # Design a new domain model from scratch
/ontology refactor # Refactor a God Interface step by step
You: Design a data model for an e-commerce product catalog
AI (with ontology skill):
Step 1 — Competency Questions:
Q1: "What categories does a product belong to?" → needs Product.categoryId: CategoryId
Q2: "Can a product have variants (size/color)?" → needs ProductVariant discriminated union
Q3: "What's the price history?" → needs PriceRecord[] with timestamps
Q4: "Is a product published or draft?" → needs status: 'draft' | 'published' | 'archived'
...
Step 4 — Class Hierarchy:
type CatalogItem =
| { kind: 'simple'; price: Money }
| { kind: 'variable'; variants: Variant[]; basePrice: Money }
| { kind: 'bundle'; items: SimpleProduct[]; discount: Percent }
Step 6 — Three-Layer Constraints:
// TypeScript
interface Product { id: ProductId; title: string; status: ProductStatus }
// Zod
const ProductSchema = z.object({ title: z.string().min(1).max(200), ... })
// SQL
CREATE TABLE products (id TEXT PRIMARY KEY, title TEXT NOT NULL CHECK(length(title) <= 200), ...)
The gold standard for evaluating data model quality, from Gruber's 1993 Stanford paper:
| Principle | Intent | ✅ Do | ❌ Don't |
|---|---|---|---|
| Clarity | Use objective, formal definitions | type UserId = string & { __brand: 'UserId' } |
userId: string // which string? |
| Coherence | No contradictions between inferred and defined | type Status = 'draft' | 'published' |
status: string // runtime surprise |
| Extendibility | Add new concepts without changing existing ones | type Content = Post | Moment | Draft // add | Poll |
interface Post { pollOptions?: ... } |
| Min. Encoding Bias | Don't depend on encoding choices | role: 'admin' | 'member' | 'guest' |
role: 0 | 1 | 2 // what does 2 mean? |
| Min. Ontological Commitment | Define only what's needed | interface Post { id; title; body } |
interface Post { ...50 optional fields } |
| Ontology Concept | TypeScript Equivalent | Example |
|---|---|---|
| Class | interface / type |
interface User { ... } |
| Subclass (is-a) | Union variant | { kind: 'admin'; permissions: string[] } |
| Property (slot) | Interface field | title: string |
| Facet (constraint) | Zod schema / branded type | z.string().min(1).max(200) |
| Instance | const data / seed row |
{ id: 'surya', name: 'Sun' } |
| Enumeration | String literal union | 'draft' | 'published' | 'archived' |
| Relation | Foreign key / ID reference | authorId: UserId |
| Cardinality | Array / optional / required | tags: string[] (0..N) |
| Domain | Interface that owns the property | Post.title (not global title) |
| Range | Property value type | createdAt: ISO8601String |
Full mapping (30+ entries) available in
docs/references/ontology-to-typescript.md
| Scenario | Without Ontology Skill | With Ontology Skill |
|---|---|---|
| Design new data model | Write interfaces by gut feeling, iterate 3 days | 7-step process: 2 hours → complete TS + SQL + Zod |
| Refactor God Interface | Don't dare touch it, keep adding optional fields | Step 4 decision tree → systematic split with type safety |
| Build taxonomy | Boolean flag explosion, 2^n runtime states | Step 3→4: enumerate terms + define hierarchy → exhaustive unions |
| Multi-dimensional scoring | Ad-hoc dimensions, redesign database later | Step 1 competency questions cover all scoring needs upfront |
| Onboard new developers | Read 3000 lines of types, ask 5 colleagues, 3 weeks | Read Ontology docs (competency questions + class diagram), 2 days |
| Cross-system consistency | TS interfaces, SQL tables, API responses all diverge | Step 6 three-layer alignment (TS + Zod + SQL), single source of truth |
| Design review | "This design feels wrong" — no standard, debates ensue | Gruber 5 principles as review checklist, evidence-based decisions |
claude-ontology-skill/
├── skills/ontology/SKILL.md # Main skill file (~800 lines)
├── agents/ontology/AGENT.md # Agent workflow definition
├── templates/ # Ready-to-use modeling templates
│ ├── 01-domain-scoping.md # Competency question templates
│ ├── 02-class-hierarchy.md # TypeScript hierarchy patterns
│ ├── 03-property-modeling.md # Property/slot modeling
│ ├── 04-constraint-facets.md # Constraint patterns (TS + Zod + SQL)
│ ├── 05-instance-data.md # Instance creation patterns
│ └── 06-inference-queries.md # Query and inference patterns
├── docs/ # Full documentation
│ ├── complete-guide.md # Complete guide (EN)
│ ├── complete-guide-zh.md # Complete guide (中文)
│ └── references/ # Reference materials
├── examples/ # Practical examples
│ ├── e-commerce/ # E-commerce domain modeling
│ ├── content-platform/ # CMS/blog domain modeling
│ └── astrology/ # Vedic astrology domain (Jyotish)
└── public/
└── wechat-qr-zh-v3.jpg # Community QR code
Contributions are welcome! Here's how:
- Fork this repository
- Create a feature branch (
git checkout -b feature/amazing-template) - Add your contribution (new templates, examples, or documentation improvements)
- Submit a Pull Request
- New domain modeling examples (healthcare, fintech, gaming, etc.)
- Templates for specific frameworks (NestJS, Prisma, tRPC)
- Translations to other languages
- Decision tree improvements
Join our community for domain modeling discussions, skill updates, and TypeScript architecture best practices:
Scan to join WeChat group / 扫码加入微信交流群
Domain modeling practice + skill discussions + TypeScript architecture
MIT — use it freely in personal and commercial projects.
- Thomas R. Gruber — for defining what an ontology is (Stanford KSL, 1993)
- Natasha Noy & Deborah McGuinness — for the 7-step Ontology 101 methodology (Stanford SMI, 2001)
- Shen Xin (沈欣) — for applying ontology methods to enterprise AI systems (2025)
- Stanford Knowledge Systems Laboratory — for the foundational research
- Built with OpenClaw — Where AI and Humans Coexist
🇨🇳 中文介绍
"本体论是概念化的显式规范。" — Thomas R. Gruber, 斯坦福 KSL, 1993
别再凭直觉写 interface 了。 这个技能教你斯坦福的 Ontology 101 方法论——适配到 TypeScript 接口、SQL 表和 Zod 验证器。通过系统化的 7 步流程，将非结构化的领域知识变成严谨的、类型安全的数据架构。
- 7 步建模流程：从 Competency Questions 到 const 数据验证，每步都有明确的 TypeScript 产出物
- 30+ 概念映射表：本体论概念→TypeScript 等价物的形式化翻译规则
- Gruber 5 准则：评判数据模型质量的黄金标准，每条都有 Do/Don't 示例
- 3 层约束对齐：TypeScript 编译时 + Zod 运行时 + SQL 存储约束，三层一致
- 5 个决策树：何时用 union vs extends、枚举 vs 字符串、内在 vs 外在属性
# 方式一：OpenClaw 技能市场
claw install ontology-skill
# 方式二：GitHub
git clone https://github.com/leofankm/claude-ontology-skill
cp -r claude-ontology-skill/skills/ontology ~/.claude/skills//ontology analyze src/types/ # 审计现有类型系统
/ontology design "电商产品目录" # 从零设计领域模型
/ontology refactor # 重构 God Interface
| 年份 | 作者 | 贡献 |
|---|---|---|
| 1993 | Gruber (斯坦福 KSL) | 定义本体论，提出 Ontolingua 翻译架构和 5 个设计准则 |
| 2001 | Noy & McGuinness (斯坦福 SMI) | 系统化为 7 步方法论，成为本体论工程标准教材 |
| 2025 | 沈欣 | 应用到企业系统（数智库三元组、ITPAO 分形、语义标注） |