Reference AI Protocol

Knowledge Source — AI Protocol reference

Knowledge Source — declarative metadata describing what to index and which adapter to use.

Knowledge Source — declarative metadata describing what to index and which adapter to use.

A KnowledgeSource is the metadata-level equivalent of an IDataEngine driver binding: it pairs a logical source description (object/file/http) with the id of an IKnowledgeAdapter plugin that will actually do the work. The adapter resolves the id at runtime via IKnowledgeService.registerAdapter.

See content/docs/protocol/knowledge.mdx for the full design.

Source: packages/spec/src/ai/knowledge-source.zod.ts

TypeScript Usage

import { FileKnowledgeSourceSchema, HttpKnowledgeSourceSchema, KnowledgeRefreshPolicySchema, KnowledgeSourceSchema, KnowledgeSourceKindSchema, ObjectKnowledgeSourceSchema } from '@objectstack/spec/ai';
import type { FileKnowledgeSource, HttpKnowledgeSource, KnowledgeRefreshPolicy, KnowledgeSource, KnowledgeSourceKind, ObjectKnowledgeSource } from '@objectstack/spec/ai';

// Validate data
const result = FileKnowledgeSourceSchema.parse(data);

FileKnowledgeSource

Properties

Property	Type	Required	Description
kind	`'file'`	✅
prefix	`string`	✅	Storage prefix
mimeTypes	`string[]`	optional (default: `[]`)

HttpKnowledgeSource

Properties

Property	Type	Required	Description
kind	`'http'`	✅
urls	`string[]`	✅
userAgent	`string`	optional

KnowledgeRefreshPolicy

Properties

Property	Type	Required	Description
onRecordChange	`boolean`	optional (default: `true`)
cron	`string \| { dialect: 'cron'; source?: string; ast?: any; meta?: object }`	optional	Cron-dialect expression for a periodic full reindex. A bare string is shorthand for `{ dialect: 'cron', source }`; the parse enforces a non-empty string or an expression envelope and normalizes to the envelope — cron syntax is not checked here, and no engine evaluates this slot: the verdict belongs to whatever external scheduler you hand the value to. `service-knowledge` does not schedule it: the value is surfaced so an automation flow / external scheduler can trigger `reindexSource`.

KnowledgeSource

Properties

Property	Type	Required	Description
id	`string`	✅	Snake_case source id
label	`string`	✅
description	`string`	optional
adapter	`string`	✅	Adapter id
adapterConfig	`Record<string, any>`	optional (default: `{}`)
source	`{ kind: 'object'; object: string; contentFields: string[]; metadataFields?: string[]; … } \| { kind: 'file'; prefix: string; mimeTypes?: string[] } \| { kind: 'http'; urls: string[]; userAgent?: string }`	✅
embedding	`{ provider: Enum<'openai' \| 'cohere' \| 'azure_openai' \| 'huggingface' \| 'local' \| 'custom'>; model: string; dimensions: integer; endpoint?: string; … }`	optional
vectorStore	`{ provider: Enum<'pgvector' \| 'chroma' \| 'qdrant' \| 'pinecone' \| 'weaviate' \| 'milvus' \| 'redis' \| …>; collection: string; endpoint?: string; secretRef?: string; … }`	optional
refresh	`{ onRecordChange?: boolean; cron?: string \| object }`	optional	Refresh / sync configuration; omitted parses to `{}` (the runtime default — the published input-shape JSON Schema cannot state it beside `cron`'s transform).
aiExposed	`boolean`	optional (default: `true`)

Nested Shape: `KnowledgeSource.source[kind='object']`

Property	Type	Required	Description
kind	`'object'`	✅
object	`string`	✅	Short object name to index
contentFields	`string[]`	✅	Fields contributing to document content
metadataFields	`string[]`	optional (default: `[]`)
where	`Record<string, any>`	optional

Nested Shape: `KnowledgeSource.source[kind='file']`

Property	Type	Required	Description
kind	`'file'`	✅
prefix	`string`	✅	Storage prefix
mimeTypes	`string[]`	optional (default: `[]`)

Nested Shape: `KnowledgeSource.embedding`

Property	Type	Required	Description
provider	`Enum<'openai' \| 'cohere' \| 'azure_openai' \| 'huggingface' \| 'local' \| 'custom'>`	✅
model	`string`	✅	Provider-specific model identifier
dimensions	`integer`	✅	Embedding vector dimensions
endpoint	`string`	optional	Custom endpoint URL
secretRef	`string`	optional	Reference to stored API key secret

Nested Shape: `KnowledgeSource.vectorStore`

Property	Type	Required	Description
provider	`Enum<'pgvector' \| 'chroma' \| 'qdrant' \| 'pinecone' \| 'weaviate' \| 'milvus' \| 'redis' \| …>`	✅
collection	`string`	✅	Collection / index / namespace name
endpoint	`string`	optional	Connection string or endpoint URL
secretRef	`string`	optional	Reference to stored credential secret
dimensions	`integer`	optional

Nested Shape: `KnowledgeSource.refresh`

Property	Type	Required	Description
onRecordChange	`boolean`	optional (default: `true`)
cron	`string \| { dialect: 'cron'; source?: string; ast?: any; meta?: object }`	optional	Cron-dialect expression for a periodic full reindex. A bare string is shorthand for `{ dialect: 'cron', source }`; the parse enforces a non-empty string or an expression envelope and normalizes to the envelope — cron syntax is not checked here, and no engine evaluates this slot: the verdict belongs to whatever external scheduler you hand the value to. `service-knowledge` does not schedule it: the value is surfaced so an automation flow / external scheduler can trigger `reindexSource`.

KnowledgeSourceKind

Union Options

This schema accepts one of the following structures:

Option 1

Properties

Property	Type	Required	Description
kind	`'object'`	✅
object	`string`	✅	Short object name to index
contentFields	`string[]`	✅	Fields contributing to document content
metadataFields	`string[]`	optional (default: `[]`)
where	`Record<string, any>`	optional

Option 2

Properties

Property	Type	Required	Description
kind	`'file'`	✅
prefix	`string`	✅	Storage prefix
mimeTypes	`string[]`	optional (default: `[]`)

Option 3

Properties

Property	Type	Required	Description
kind	`'http'`	✅
urls	`string[]`	✅
userAgent	`string`	optional

ObjectKnowledgeSource

Properties

Property	Type	Required	Description
kind	`'object'`	✅
object	`string`	✅	Short object name to index
contentFields	`string[]`	✅	Fields contributing to document content
metadataFields	`string[]`	optional (default: `[]`)
where	`Record<string, any>`	optional

Knowledge Document

Knowledge Document / Chunk / Hit — canonical shapes shared by every IKnowledgeAdapter implementation.

Conversation

Multi-turn AI conversations with token budget management. Enables context preservation, conversation history, and token optimization.