Knowledge Schema
How do you give a domain enough shape that people and agents can learn, retrieve, and improve it together?
A knowledge schema maps unfamiliar territory against territory you already own. The known structure becomes a Rosetta Stone. You stop learning from scratch and start translating—then deeply investigate where translation fails.
The wider discipline is Knowledge Organization (KO). Knowledge Engineering applies that discipline in computational systems. A practical Knowledge Organization System (KOS) may combine four layers:
| Layer | Job | Add it when... |
|---|---|---|
| Taxonomy | Place concepts in a useful hierarchy | people cannot predict where knowledge belongs |
| Thesaurus | Connect canonical terms, aliases, and related concepts | different groups use different words or need sideways discovery |
| Ontology | Type entities, properties, states, and relationships | agents or software must validate and reason across the map |
| KOS | Govern the combined structures, owners, lifecycle, and retrieval routes | the map serves multiple readers, agents, and change processes |
This is a capability ladder, not a compulsory sequence. A small glossary may solve the problem. Formal ontology earns its cost only when typed reasoning or validation changes a real decision.
For naming, the applied schema is the Name Integrity Stack: ontology asks what exists, epistemology asks how we know, taxonomy asks where it belongs, nomenclature asks what it is called, and axiology asks why the name improves action.
The Five-Gate Unit-of-Knowledge Protocol
Use the same five questions for every concept, page, field, relationship, or canonical name. Each gate must produce an explicit output before the next begins.
| Gate | Question | Required output | Block when... |
|---|---|---|---|
| Ontology | What exists? | Entity or claim type, boundaries, states, and relationships | the thing is only a vague topic or duplicated entity |
| Epistemology | How may we know and update it? | Source, confidence, freshness, verifier, and contradiction path | evidence or update authority is unknown |
| Taxonomy | Where does it belong? | Owning domain, reader job, artifact type, lifecycle, and consumers | two canonical homes remain or a mixed artifact has not been split |
| Nomenclature | What is it called? | Canonical term, route or field, aliases, and naming rule | the name hides its kind or conflicts with an authority |
| Axiology | Why should it exist? | Decision, action, metric, or question it makes clearer | no observable use justifies retrieval or maintenance cost |
The gates are ordered because later answers depend on earlier truth. Do not choose a clever name before knowing what the thing is. Do not place it before knowing who needs it. Do not retain it when its only value is that it can be stored.
Prompt
Design this knowledge unit without inventing missing truth.
1. Ontology: name the entity/claim type, boundaries, states, and typed relationships.
2. Epistemology: name sources, confidence, freshness, verifier, and update trigger.
3. Taxonomy: choose domain, reader job, artifact type, lifecycle, owner, and consumers.
4. Nomenclature: propose one canonical term/route plus aliases and the rule it follows.
5. Axiology: state the decision, action, metric, or next question this unit enables.
Stop at the first unresolved gate. Return the missing evidence instead of filling the gap with prose.
Relationships Before Connections
A schema is not a list of things. It is a map of things in relation.
Ontology names the entities, states, boundaries, and relationships the system treats as real. A connection is an activated relationship: a relationship with a pipe, affordance, or flow. It can carry information, value, intent, trust, proof, energy, or attention.
Every page should make its relationships legible.
- What does it depend on?
- What does it explain?
- What does it point to?
- What does it prove?
- What does it contradict?
- What next action does it enable?
For an index page, the relationships are the neighborhood: parent, child routes, adjacent domains, and choice logic. For a knowledge page, the relationships are the concept map: upstream assumptions, downstream applications, examples, evidence, questions, and failure modes.
The Procedure
Any agent or person can follow this to rapidly acquire a new domain.
1. Pick the Anchor
Choose the domain you know deepest. It becomes column 1 of every comparison table. The anchor must be experiential — something you built with, not something you read about.
| Good Anchor | Bad Anchor |
|---|---|
| Years of EVM/Solidity development | Read a blog post about Ethereum |
| Built production P&ID systems | Saw a factory diagram once |
| Shipped React apps | Watched a React tutorial |
2. Map Concepts
For each concept in the new domain, find the equivalent in the anchor. Build the table.
| Anchor (Known) | Target (New) | Gap Type |
|---|---|---|
| Concept A | Equivalent A | Direct mapping |
| Concept B | Different B | Different model |
| Concept C | Nothing needed | Absence — target removes the need |
| No equivalent | Concept D | Genuinely new |
3. Classify the Gaps
Four gap types. Each requires a different learning strategy.
| Gap Type | What It Means | Learning Strategy |
|---|---|---|
| Direct mapping | Same concept, different syntax | Fast — learn the syntax, skip the theory |
| Different model | Same problem, different solution | Medium — understand why the new model exists |
| Absence | Anchor has it, target doesn't need it | Unlearn — the old concept is a liability here |
| Genuinely new | No anchor equivalent | Deep — this is where real learning happens |
4. Genuinely New
Everything that maps directly is vocabulary swap. You pick it up by doing. Spend your time on the "genuinely new" and "different model" rows — these are where the new domain's power lives and where your anchor can mislead you.
5. Build With It
Schema without application is theory. Build something small that forces you through each gap type. The build reveals which mappings were wrong.
6. Update the Schema
After building, go back and correct the table. Some "direct mappings" turn out to be "different models" under pressure. Some "genuinely new" concepts turn out to be familiar patterns in disguise. The corrected table is the legacy for the next agent.
From Schema To Knowledge Architecture
A schema explains how concepts map. A knowledge architecture also names who can change the map, how the map moves through time, which controls keep it honest, which representations make it usable, and what level of knowledge each artifact claims.
Use this checklist when a schema becomes important enough to govern:
| Dimension | Question | Field or artifact |
|---|---|---|
| Reality | What exists? | ontology, entities, states, boundaries, relationships |
| Evidence | How do we know? | source, proof path, freshness rule, validation gate |
| Structure | Where does it belong? | taxonomy, surface, domain, consumer, lifecycle |
| Naming | What is it called? | nomenclature, route, slug, canonical term |
| Value | Why does it matter? | axiology, decision, action, metric, priority |
| Agents | Who can read, use, or change it? | owner, actor, authority, permission, capability |
| Flow | How does it move through time? | status, confidence, last validated, review interval |
| Controls | What keeps change safe? | approval path, breaking-change rule, sunset policy |
| Representation | How must it be exposed? | table, diagram, worked example, explanation, test |
| Level | What claim does this artifact make? | data, information, knowledge, or wisdom |
Minimum governed schema row:
| Entity or claim | Type | Relationships | Canonical term | Aliases | Home | Level | Status | Evidence | Owner | Review trigger | Value |
|---|---|---|---|---|---|---|---|---|---|---|---|
| ? | ? | ? | ? | ? | ? | ? | ? | ? | ? | ? | ? |
Lifecycle states:
proposed -> experimental -> proven -> standard -> legacy -> deprecated
- Proposed — useful hypothesis, not yet tested.
- Experimental — being used in one real build, decision, or diagram.
- Proven — survived application and corrected the schema.
- Standard — reusable enough to teach or govern others.
- Legacy — still referenced, but no longer the preferred model.
- Deprecated — kept only for migration, history, or compatibility.
Representation contract for important schemas:
- Reference — the table or canonical field list.
- Diagram — the flow, A&ID, or relationship map.
- Worked example — one applied case that forces the gaps to surface.
- Explanation — why this schema exists and what trade-offs it encodes.
- Validation — a test, review cadence, receipt, or proof path.
Shape a Playbook Section
The Wiki Control Plane applies this method to the public Playbook. Use the schema to decide the knowledge shape; use the Wiki authorities to implement it.
| Schema decision | Playbook control |
|---|---|
| What subject owns the knowledge? | Folder Ownership and the canonical parent hub |
| What job does the artifact perform? | Page Types and its matching template |
| Which terms are canonical? | Naming Standards and the Language System |
| How should it be discovered? | title, description, retrieval_trigger, typed links, parent route, and generated projections |
| What keeps it current? | claim state, evidence boundary, owner, review trigger, checks, and Git history |
Use this minimum page-shape contract for a substantive Playbook page:
type: concept | playbook | hub | domain-map | evidence | glossary | decision-record | map-of-reality
title: "Canonical entity or reader-facing question"
description: "What the page helps the reader understand, decide, or do."
page_job: "The exact reader decision or action this page enables."
retrieval_trigger: "Load when this situation or decision occurs."
template: "The pattern required by the page type."
template_url: "/playbook/standards/templates/..."
Frontmatter makes a page retrievable; it does not make the page valuable. The body must still teach one model, preserve its evidence boundary, offer a useful action, and route the reader onward.
Living Knowledge Without Ontology Theatre
A KOS becomes living when use and evidence can change its next cycle—not when it is labelled “living.”
capture use or evidence
→ detect an orphan, collision, stale claim, failed retrieval, or new relationship
→ review through the five gates
→ update the canonical source and its consumers
→ regenerate projections
→ test whether retrieval or decisions improved
Humans retain authority over values, contested meaning, disclosure, and durable setpoint changes. Agents can detect structural drift, propose links, check metadata, identify stale evidence, and regenerate derived maps. Usage signals inform review; popularity alone must not redefine truth.
Evidence that the system is evolving includes fewer duplicate authorities, successful intent-based retrieval, resolved stale claims, shorter placement time, and a later decision that reuses the retained learning. More nodes and links are volume, not proof.
Failure Modes
- Taxonomy as truth: a folder position is treated as evidence that the concept is valid.
- Ontology theatre: types and edges multiply without supporting validation or decisions.
- Alias drift: several terms point sideways but none has a canonical owner.
- Axiology-free chunks: content is retrievable but cannot change an action or question.
- Popularity feedback: frequently retrieved content becomes “true” without evidence review.
- Generated authority: an index or graph projection is edited as though it owns its source.
- Premature permanence: research or agent synthesis is promoted before human review and proof.
Level rule:
- Data — raw fields, logs, facts, or observations.
- Information — structured records, tables, schemas, or routes.
- Knowledge — validated mappings, patterns, procedures, or standards.
- Wisdom — judgment rules that improve decisions across situations.
Worked Examples
EVM → Move (Smart Contracts)
EVM as reference schema for understanding Sui/Move. Full comparison at Smart Contract Standards.
| EVM (Known) | Move (New) | Gap Type |
|---|---|---|
| Global state | Objects with ownership | Different model — no shared mutable state |
msg.sender | tx_context::sender() + capabilities | Different model — compiler-enforced, not convention |
| ERC-20 interface | sui::coin module | Direct mapping |
onlyOwner modifier | Capability object (AdminCap) | Different model — no runtime modifiers |
OpenZeppelin ReentrancyGuard | Nothing needed | Absence — Move makes re-entrancy impossible |
OpenZeppelin Ownable | two_step_transfer wrapper | Direct mapping — choreography on top of capabilities |
| Proxy upgrade pattern | sui client upgrade with policy | Different model — protocol-level, not pattern-level |
| No equivalent | PTBs (1,024 atomic ops) | Genuinely new — no EVM equivalent at this scale |
| No equivalent | zkLogin (OAuth → address) | Genuinely new — protocol-level account abstraction |
| No equivalent | Linear types (move only, never copy) | Genuinely new — entire vulnerability classes vanish |
The "genuinely new" rows — PTBs, zkLogin, linear types — are where deep learning is required. Everything else accelerates through translation.
P&ID → A&ID (Agent Nomenclature)
Process engineering as reference schema for Agent & Instrument Diagrams.
| P&ID (Known) | A&ID (New) | Gap Type |
|---|---|---|
| Process equipment | Agents (HA, DA, PA, OA) | Direct mapping |
| Instruments (sensors, valves) | Instruments (tokens, identity, incentives) | Direct mapping |
| Pipelines | Protocols (data flows, value flows) | Direct mapping |
| Control loops | Feedback loops (VVFL, tokenomics) | Direct mapping |
| ISA-5.1 symbol codes | A&ID symbol codes (DA-ST01) | Direct mapping |
| ANSI valve assemblies | Standard fittings (OpenZeppelin) | Direct mapping |
| No equivalent | Smart contracts as intelligent hyperlinks | Genuinely new |
| No equivalent | Verifiable settlement (on-chain proof) | Genuinely new |
P&ID → A&ID is almost entirely direct mapping. That's what makes it powerful — process engineers can read agent diagrams immediately. The genuinely new concepts (smart contracts, on-chain settlement) sit on top of a familiar structure.
Traditional Dev → AI Tooling
Traditional software architecture as reference schema for understanding the AI tools layer.
| Traditional Dev (Known) | AI Tooling (New) | Gap Type |
|---|---|---|
| IDE (VSCode, IntelliJ) | Agentic framework (Claude Code, Gemini CLI) | Different model — the IDE doesn't run code; the framework orchestrates agents that do |
| Runtime / execution engine | Agent engine (ElizaOS, CrewAI, Clawbot) | Direct mapping — both implement a loop that executes instructions |
| API / SDK | Agent protocol (MCP, A2A) | Different model — protocols coordinate autonomous agents, not just function calls |
| Linter / formatter | Hook (shell scripts on agent actions) | Direct mapping — deterministic checks on output |
| Environment variable | Rule (always-loaded constraint in CLAUDE.md) | Different model — rules are natural language, not key-value pairs |
| CI/CD pipeline | Skill (invocable workflow) | Different model — skills are markdown, invoked by name, not YAML jobs |
| Long-running server | Persistent agent (daemon mode engine) | Direct mapping |
| Lambda / serverless function | Stateless agent runner (per-task subagent) | Direct mapping |
| No equivalent | Cascade (Mantra → Rule → Hook → System) | Genuinely new — intention becoming automated enforcement through natural language |
The "genuinely new" row — the Cascade — is where most traditional developers get stuck. They treat CLAUDE.md like an .env file (key-value store) and rules like linter configs (on/off toggles). The Cascade is neither. It's intention compressed into a compounding system. See Mantra.
The Lindy Dimension
The Lindy Effect applies to schemas: the longer a mapping survives real use, the more trustworthy it is. A direct mapping that has worked for years (P&ID symbols → A&ID codes) is more reliable than one created yesterday.
Standard fittings demonstrate this. OpenZeppelin's EVM patterns are Lindy — battle-tested since 2016. When ported to Move, the patterns transfer even though the implementation is new. The schema (access control, safe math, time locks) survives across platforms because the underlying problems are the same.
The Matrix
Jobs × Attributes = Visibility.
| Job | Artifact | Owner | Status |
|---|---|---|---|
| ? | ? | ? | ? |
Each row is a job. Each column is what you need to know. Empty cells are blind spots. The reference schema procedure above is how you fill the cells fast — by translating from a domain where you already filled them.
Applied:
- Marketing Protocols — 25 jobs × 8 attributes
- Jobs To Be Done — What customers hire products to do
- Smart Contract Standards — EVM × Move × SVM comparison tables
Context
- pairs-with Matrix Thinking — Making invisible visible
- depends-on Knowledge Stack — Primitives → Protocols → Standards → Platform
- instance-of Smart Contract Standards — Worked example: EVM as reference schema for Move
- instance-of A&ID Template — Worked example: P&ID as reference schema for agent nomenclature
- depends-on Naming Standards — Consistent taxonomy makes schemas navigable
- applies-to Data Footprint — The data model IS the knowledge schema for any domain
- pairs-with Tight Five — The schema that organises schemas
- pairs-with Hacker Laws — Lindy Effect: survival validates the schema
- applies-to Jobs To Be Done — What customers hire products to do
- applies-to Work Charts — Human/AI capability mapping
Links
- Schema Development — Psychology of knowledge schemas
- Diátaxis — Four documentation types serve four learning needs
Questions
How do you know when a reference schema is helping you learn — versus trapping you in the old model's assumptions?
- Which "genuinely new" concept in your current learning target would be invisible if you only translated from your anchor?
- When the anchor has a concept the target deliberately omits (like
ReentrancyGuardin Move), is the absence a feature or a blind spot you'll pay for later? - What's the minimum number of "genuinely new" rows that justify learning a new domain — versus staying in the anchor domain and waiting for it to catch up?
- If an agent follows this procedure with a different anchor, do they arrive at the same schema — or does the anchor determine what you see?