Skip to content

feat: add knowledge wiki schema #75

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mindsocket merged 2 commits into from
Apr 5, 2026
Merged

feat: add knowledge wiki schema #75

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
66cbcc4
feat: add knowledge wiki schema
mindsocket Apr 5, 2026
5a9776c
refactor: address PR review feedback on knowledge wiki schema
mindsocket Apr 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
221 changes: 221 additions & 0 deletions schemas/knowledge_wiki.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,221 @@
{
"$schema": "https://raw.githubusercontent.com/mindsocket/ost-tools/main/schemas/generated/_ost_tools_schema_meta.json",
"$id": "ost-tools://knowledge_wiki",
"title": "Knowledge Wiki",
"description": "Lightweight schema for LLM-maintained knowledge wikis. Supports source pages, concept pages, syntheses, and notes. Designed for compounding knowledge bases where the LLM creates and maintains wiki pages from raw sources.\n\nFlat entity model — no hierarchy, no required parent links. Wikilinks between any pages are valid for arbitrary cross-referencing. The schema validates structure and provenance; it does not constrain meaning.\n\nBased on the pattern described in Karpathy's LLM Wiki (2026).",
"$metadata": {
"aliases": {
"source_summary": "source",
"study": "source",
"article": "source",
"paper": "source",
"research": "source",
"journal": "note"
},
"relationships": [
{
"parent": "source",
"type": "source",
"field": "sources",
"fieldOn": "child",
"multiple": true
},
{
"parent": "source",
"type": "synthesis",
"field": "sources",
"fieldOn": "child",
"multiple": true
},
{
"parent": "concept",
"type": "synthesis",
"field": "concepts",
"fieldOn": "child",
"multiple": true
}
],
"rules": [
{
"id": "synthesis-references-sources",
"category": "coherence",
"description": "Syntheses should reference at least one contributing source in their sources array",
"type": "synthesis",
"check": "$exists(current.sources) and $length(current.sources) >= 1"
},
{
"id": "concept-has-summary",
"category": "best-practice",
"description": "Concept pages should have a short summary for index discoverability",
"type": "concept",
"check": "$exists(current.summary) and $length(current.summary) > 0"
}
]
},
"oneOf": [
{
"type": "object",
"description": "A processed summary of a raw source (article, paper, book, video, thread, podcast, etc.). Captures key information from the source in structured form with provenance.",
"allOf": [
{ "$ref": "ost-tools://_ost_tools_base#/$defs/baseNodeProps" },
{ "$ref": "ost-tools://_ost_tools_base#/$defs/ostEntityProps" }
],
"properties": {
Copy link
Copy Markdown
Owner Author

@mindsocket mindsocket Apr 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add an optional property that is a wikilink to a local copy of the source.

"type": { "const": "source" },
"url": {
"type": "string",
"description": "URL of the original source"
},
"local_copy": {
"$ref": "ost-tools://_ost_tools_base#/$defs/wikilink",
"description": "Wikilink to a local copy of the source (e.g. a saved PDF or clipped note)"
},
"author": {
"type": "string",
"description": "Author or creator of the source"
},
"book": {
"type": "string",
"description": "Book title and author if the source is a book"
},
"published_date": {
"type": "string",
"description": "Original publication date (ISO 8601 or natural language)"
},
"source_type": {
"type": "string",
"description": "Kind of source material. Free-form — common values include article, paper, book, video, podcast, thread, substack, tweet, website. Not enum-constrained to allow evolving vocabulary."
},
"sources": {
"type": "array",
"items": { "$ref": "ost-tools://_ost_tools_base#/$defs/wikilink" },
"description": "Wikilinks to other source pages that this one references or extends"
}
},
"required": ["type", "url"],
"additionalProperties": true,
"examples": [
{
"type": "source",
"title": "The Design of Everyday Things - Don Norman",
"author": "Don Norman",
"url": "https://example.com/design-of-everyday-things",
"source_type": "book",
"tags": ["design", "ux", "psychology"],
"status": "active"
}
]
},
{
"type": "object",
"description": "A concept or entity page — defines and frames a specific idea, mechanism, or domain term. May draw from multiple sources. The building blocks of the wiki's knowledge graph.",
"allOf": [
{ "$ref": "ost-tools://_ost_tools_base#/$defs/baseNodeProps" },
{ "$ref": "ost-tools://_ost_tools_base#/$defs/ostEntityProps" }
],
"properties": {
"type": { "const": "concept" },
"sources": {
"type": "array",
"items": { "$ref": "ost-tools://_ost_tools_base#/$defs/wikilink" },
"description": "Wikilinks to source pages that contributed to this concept"
},
"related": {
"type": "array",
"items": { "$ref": "ost-tools://_ost_tools_base#/$defs/wikilink" },
"description": "Wikilinks to related concept or synthesis pages"
}
},
"required": ["type"],
"additionalProperties": true,
"examples": [
{
"type": "concept",
"title": "Affordance",
"summary": "A property of an object that signals how it can be used, first described by Gibson and popularised in design by Norman",
"tags": ["design", "ux"],
"status": "active"
}
]
},
{
"type": "object",
"description": "A synthesis page — connects multiple concepts and sources into a coherent model, framework, or thesis. The highest-value pages in a knowledge wiki. Must reference contributing sources.",
"allOf": [
{ "$ref": "ost-tools://_ost_tools_base#/$defs/baseNodeProps" },
{ "$ref": "ost-tools://_ost_tools_base#/$defs/ostEntityProps" }
],
"properties": {
"type": { "const": "synthesis" },
"sources": {
"type": "array",
"items": { "$ref": "ost-tools://_ost_tools_base#/$defs/wikilink" },
"description": "Wikilinks to source pages this synthesis draws from"
},
"concepts": {
"type": "array",
"items": { "$ref": "ost-tools://_ost_tools_base#/$defs/wikilink" },
"description": "Wikilinks to concept pages this synthesis connects"
}
},
"required": ["type"],
"additionalProperties": true,
"examples": [
{
"type": "synthesis",
"title": "Affordances and feedback loops in interface design",
"summary": "How Norman's affordance model and feedback principles combine to explain intuitive vs confusing interfaces",
"sources": ["[[The Design of Everyday Things - Don Norman]]"],
"concepts": ["[[Affordance]]", "[[Feedback loop]]"],
"status": "active"
}
]
},
{
"type": "object",
"description": "Personal notes, journal entries, appointments, experiential records. Your own data about your journey — not sourced from external material.",
"allOf": [
{ "$ref": "ost-tools://_ost_tools_base#/$defs/baseNodeProps" },
{ "$ref": "ost-tools://_ost_tools_base#/$defs/ostEntityProps" }
],
"properties": {
"type": { "const": "note" },
"date": {
"type": "string",
"description": "Date this entry was created or relates to"
}
},
"required": ["type"],
"additionalProperties": true,
"examples": [
{
"type": "note",
"title": "Reflections after reading chapter 3",
"date": "2024-03-15",
"tags": ["reading-log"],
"status": "active"
}
]
},
{
"type": "object",
"description": "The wiki index — a catalog of all pages with links, summaries, and metadata. Updated by the agent on ingest. Used as the primary navigation entry point.",
"allOf": [
{ "$ref": "ost-tools://_ost_tools_base#/$defs/baseNodeProps" },
{ "$ref": "ost-tools://_ost_tools_base#/$defs/ostEntityProps" }
],
"properties": {
"type": { "const": "index" }
},
"required": ["type"],
"additionalProperties": true,
"examples": [
{
"type": "index",
"title": "index",
"status": "active"
}
]
}
]
}