quick-reference.mdx

title	Quick reference — every metadata type
navTitle	Quick Reference Guide
description	Look up any ObjectStack metadata type fast — the key schemas of every protocol category on one page, with common patterns and search tips.

Fast lookup for the ObjectStack protocols organized by category.

Click on any protocol name to view its complete API reference.

Reading the counts. Every heading below says (N of M schemas). N is how many protocols this table lists; M is how many reference pages the matching content/docs/references/<category>/ directory publishes. These tables are a curated fast lookup, not a mirror of the reference tree — N < M is normal and intended. Both numbers are checked by pnpm check:quick-reference-counts, so a category that gains or loses a page shows up here instead of drifting unnoticed. A row marked ↗ links outside its category's reference tree: it is one of the N rows, but it is not one of the M pages. Categories that have no section here at all are named under Categories Without a Section — that curation is stated, not left implicit.

Data Protocol (15 of 30 schemas)

Core business logic and data modeling schemas.

Protocol	Source File	Key Schemas	Purpose
Field	field.zod.ts	Field, FieldType, SelectOption	Field types for data modeling
Object	object.zod.ts	Object, ObjectCapabilities	Object/table definitions
Query	query.zod.ts	Query, QueryAST	Query AST with joins, aggregations
Filter	filter.zod.ts	QueryFilter, FilterCondition	Advanced filtering operators
Validation	validation.zod.ts	ValidationRule	Business validation rules
Datasource	datasource.zod.ts	Datasource, DriverDefinition	Database connection configs
Analytics	analytics.zod.ts	Analytics	Data analytics and aggregation
Mapping	mapping.zod.ts	ImportFieldMapping	Field transformation mappings
Hook	hook.zod.ts	Hook, HookEvent	Lifecycle event hooks
Data Engine	data-engine.zod.ts	DataEngine	Data engine configuration
Driver	driver.zod.ts	Driver, DriverCapabilities	Database driver interface
SQL Driver	driver-sql.zod.ts	SQLDriverConfig, SQLDialect	SQL-specific driver
NoSQL Driver	driver-nosql.zod.ts	NoSQLDriverConfig	NoSQL-specific driver
Postgres Driver	driver/postgres.zod.ts	PostgresConfig	PostgreSQL configuration
Mongo Driver	driver/mongo.zod.ts	MongoConfig	MongoDB configuration

UI Protocol (10 of 16 schemas)

Presentation layer - views, forms, dashboards, and app branding.

Protocol	Source File	Key Schemas	Purpose
View	view.zod.ts	View, ListView, FormView	List and form view configurations
Page	page.zod.ts	Page, PageComponent	FlexiPage layouts
App	app.zod.ts	App, NavigationItem	Application navigation structure
Dashboard	dashboard.zod.ts	Dashboard, DashboardWidget	Dashboard layouts and widgets
Dataset	dataset.zod.ts	Dataset, DatasetDimension, DatasetMeasure	Semantic-layer datasets for dashboards (ADR-0021)
Report	report.zod.ts	Report, ReportType	Report definitions
Action	action.zod.ts	Action, ActionType	UI button actions
Component	component.zod.ts	PageComponent variants	Reusable UI components
Chart	chart.zod.ts	Chart, ChartType	Chart definitions
Widget Contract ↗	widget.zod.ts	FieldWidgetProps	Props a custom field widget receives — the contract is documented with ObjectUI, outside references/ui/

Kernel Protocol (17 of 29 schemas)

Plugin architecture, manifests, and kernel runtime.

Protocol	Source File	Key Schemas	Purpose
Manifest	manifest.zod.ts	Manifest	Package manifest (objectstack.config.ts)
Context	context.zod.ts	KernelContext	Runtime execution context
Plugin	plugin.zod.ts	Plugin, PluginLifecycle	Plugin system interface
Plugin Capability	plugin-capability.zod.ts	PluginCapability	Plugin capability declarations
Plugin Lifecycle Advanced	plugin-lifecycle-advanced.zod.ts	PluginHealthCheck, HotReloadConfig	Host-driven lifecycle library inputs
Plugin Loading	plugin-loading.zod.ts	PluginLoadingConfig	Plugin loading and init
Plugin Registry	plugin-registry.zod.ts	PluginRegistryEntry, PluginVendor	Plugin registry entries and quality metrics
Plugin Security	plugin-security.zod.ts	PluginSecurityProtocol, SBOM	Plugin security policies
Plugin Security Advanced	plugin-security-advanced.zod.ts	KernelSecurityPolicy, PluginPermission	Plugin sandboxing
Plugin Structure	plugin-structure.zod.ts	OpsPluginStructure	Plugin file conventions
Plugin Validator	plugin-validator.zod.ts	ValidationResult, PluginMetadata	Plugin validation
Plugin Versioning	plugin-versioning.zod.ts	PluginCompatibilityMatrix, DeprecationNotice	Version compatibility
Service Registry	service-registry.zod.ts	ServiceRegistryConfig, ServiceMetadata	Service discovery
Startup Orchestrator	startup-orchestrator.zod.ts	PluginStartupResult	The per-plugin result the kernel returns for every plugin it starts
Events ↗	events.zod.ts	Event, EventBusConfig	System event bus — the hand-written guide, outside references/kernel/ (which splits the same surface across six events-* pages)
Metadata Loader	metadata-loader.zod.ts	MetadataLoaderContract	Metadata loading
Package Registry	package-registry.zod.ts	InstalledPackage, InstallPackageRequest	Package resolution

System Protocol (16 of 37 schemas)

Runtime environment, logging, jobs, caching, and observability.

Protocol	Source File	Key Schemas	Purpose
Auth Config	auth-config.zod.ts	AuthConfig	Authentication configuration
Cache	cache.zod.ts	CacheConfig	Caching layer
Collaboration	collaboration.zod.ts	Collaboration	Real-time collab
Encryption	encryption.zod.ts	Encryption	Encryption & keys
HTTP Server	http-server.zod.ts	RouteHandlerMetadata, MiddlewareConfig	Route + middleware metadata
Job	job.zod.ts	Job, JobSchedule	Background job queue
Logging	logging.zod.ts	LoggingConfig	Structured logging
Metadata Persistence	metadata-persistence.zod.ts	MetadataHistoryRecord, MetadataDiffResult	Metadata storage
Metrics	metrics.zod.ts	Metrics	Application metrics
Migration	migration.zod.ts	Migration	Schema migration
Notification	notification.zod.ts	Notification	Notifications
Object Storage	object-storage.zod.ts	BucketConfig, ObjectMetadata	Object storage
Search Engine	search-engine.zod.ts	SearchConfig, SearchIndexConfig	Full-text search
Tracing	tracing.zod.ts	Tracing	Distributed tracing
Translation	translation.zod.ts	Translation	i18n support
Worker	worker.zod.ts	Worker	Background workers

AI Protocol (11 of 12 schemas)

AI/ML capabilities - agents, skills, tools, MCP exposure, RAG, and cost tracking.

Protocol	Source File	Key Schemas	Purpose
Agent	agent.zod.ts	Agent, AITool	AI agent definitions
Skill	skill.zod.ts	Skill, SkillTriggerCondition	Reusable agent skills
Tool	tool.zod.ts	Tool, ToolCategory	Agent tool definitions
MCP	mcp.zod.ts	MCPServerRef, MCPToolBinding	MCP server exposure and tool bindings
Model Registry	model-registry.zod.ts	ModelRegistry, ModelProvider	LLM model management
Conversation	conversation.zod.ts	ConversationSession	Conversation management
Embedding	embedding.zod.ts	EmbeddingModel, VectorStore	Embedding models and vector stores
Knowledge Source	knowledge-source.zod.ts	KnowledgeSource, KnowledgeRefreshPolicy	RAG ingestion sources
Knowledge Document	knowledge-document.zod.ts	KnowledgeDocument, KnowledgeChunk	RAG documents and chunks
Usage	usage.zod.ts	AIUsageRecord, TokenUsage	AI usage and cost tracking
Solution Blueprint	solution-blueprint.zod.ts	BlueprintObject, BlueprintApp	Blueprint format for AI app generation

API Protocol (17 of 32 schemas)

REST endpoints, real-time subscriptions, and discovery.

Protocol	Source File	Key Schemas	Purpose
Contract	contract.zod.ts	BaseResponse, BulkRequest	API contract definitions
Endpoint	endpoint.zod.ts	ApiEndpoint, ApiMapping	REST endpoint configuration
Router	router.zod.ts	Router, Route	API routing rules
OData	odata.zod.ts	ODataQuery	OData protocol support
Realtime	realtime.zod.ts	Subscription, RealtimeEvent	WebSocket subscriptions
WebSocket	websocket.zod.ts	WebSocketConfig	WebSocket protocol
Discovery	discovery.zod.ts	Discovery, ServiceInfo	API discovery and metadata
Batch	batch.zod.ts	BatchConfig, CrossObjectBatchRequest	Batch API processing
HTTP Cache	http-cache.zod.ts	CacheControl, ETag	HTTP caching
Errors	errors.zod.ts	ErrorResponse	Error responses
Protocol	protocol.zod.ts	BatchDataRequest, CheckPermissionRequest	Console/client request-response contracts
REST Server	rest-server.zod.ts	RestApiConfig, CrudEndpointsConfig	REST server config
Auth	auth.zod.ts	LoginRequest, Session	API authentication
Analytics	analytics.zod.ts	Analytics	API usage analytics
Documentation	documentation.zod.ts	Documentation	API docs generation
Metadata	metadata.zod.ts	Metadata	API metadata endpoints
Storage	storage.zod.ts	Storage	API storage operations

Automation Protocol (3 of 14 schemas)

Flows, approvals, and integrations. A record's lifecycle transitions are a state_machine validation rule on the object (see State Machine).

Protocol	Source File	Key Schemas	Purpose
Flow	flow.zod.ts	Flow, FlowNode	Visual workflow builder
Approval	approval.zod.ts	ApprovalNodeConfig	Flow approval-node config
Webhook	webhook.zod.ts	Webhook	Outbound webhooks

Security Protocol (3 of 5 schemas)

Access control, permissions, and row-level security.

Protocol	Source File	Key Schemas	Purpose
Permission	permission.zod.ts	ObjectPermission	Object-level permissions
RLS	rls.zod.ts	RowLevelSecurityPolicy	Row-level security filters
Sharing	sharing.zod.ts	SharingRule	Record sharing rules

Identity Protocol (4 of 5 schemas)

User identity, organizations, and position management.

Protocol	Source File	Key Schemas	Purpose
Identity	identity.zod.ts	Identity, User	User identity management
Organization	organization.zod.ts	Organization	Multi-organization support
Position	position.zod.ts	Position	Permission-set distribution (岗位, ADR-0090)
SCIM	scim.zod.ts	SCIMUser, SCIMGroup	SCIM 2.0 provisioning

Marketplace Protocol (2 of 4 schemas)

The package & marketplace format — what a package author publishes and what the marketplace answers with. (The cloud control plane's own contracts — environments, tenants, the developer portal, marketplace administration — are not an open-source protocol; they left @objectstack/spec with the ./cloud subpath and live in the cloud repo beside their producer.)

Protocol	Source File	Key Schemas	Purpose
Package	package.zod.ts	Package, CreatePackageRequest, PackageTranslations	Package identity and listing text
Marketplace	marketplace.zod.ts	MarketplaceListing, PackageSubmission	Plugin marketplace

Integration Protocol (1 of 1 schema)

External system connectors — one protocol (ADR-0097): a connector entry is either a catalog descriptor or a provider-bound instance that a generic executor (connector-openapi / connector-mcp) materializes at boot. The per-provider schema "templates" (SaaS / database / file-storage / message-queue / GitHub / Vercel) were removed in #4480: provider shapes come from the provider itself, not from hand-written spec files.

Protocol	Source File	Key Schemas	Purpose
Connector	connector.zod.ts	Connector	The connector protocol — auth, sync, webhooks, rate limiting

Shared Protocol (5 of 10 schemas)

Common utilities used across all protocols.

Protocol	Source File	Key Schemas	Purpose
Expression	expression.zod.ts	Expression, ExpressionInput	CEL expression values and inputs
HTTP	http.zod.ts	HttpRequest, HttpMethod, CorsConfig	HTTP utilities
Identifiers	identifiers.zod.ts	SystemIdentifier, SnakeCaseIdentifier	Standard ID patterns
Mapping	mapping.zod.ts	FieldMapping	Field mapping utilities
Connector Auth ↗	connector-auth.zod.ts	ConnectorInstanceAuth	Declarative connector auth (ADR-0097). The file sits in src/shared/ but @objectstack/spec/shared does not publish it — it reaches consumers through @objectstack/spec/integration, so it is documented on the Connector page

QA Protocol (1 of 1 schema)

Testing and quality assurance.

Protocol	Source File	Key Schemas	Purpose
Testing	testing.zod.ts	TestSuite	Declarative test definitions

Categories Without a Section

content/docs/references/ holds one more category directory that deliberately gets no section above. Curation happens at the category level as well as inside each table, and this is where it is stated. The same gate reads this table, so a new category directory — or a page landing in this one — goes red until this page is updated.

Category directory	Pages	Why it has no section
studio	3	Designer-facing metadata (flow-builder, object-designer, plugin) — Studio's own authoring surfaces, not protocols an app declares. Reach them from the reference index.

---

Common Patterns

Naming Conventions

<Tabs items={['Configuration Keys', 'Data Values', 'Schema Names']}> typescript // Property names in schemas: camelCase { maxLength: 100, defaultValue: 'example', inlineHelpText: 'Enter a value' } typescript // Machine identifiers in data: snake_case { name: 'project_task', object: 'customer', field: 'first_name' } typescript // Export names: PascalCase + Schema suffix export const FieldSchema = z.object({...}); export type Field = z.infer<typeof FieldSchema>;

Common Imports

{/* os:check */}

// Data protocols
import { FieldSchema, ObjectSchema, QuerySchema } from '@objectstack/spec/data';

// UI protocols
import { ViewSchema, AppSchema, DashboardSchema } from '@objectstack/spec/ui';

// Kernel protocols
import { ManifestSchema, PluginSchema } from '@objectstack/spec/kernel';

// System protocols
import { LoggerConfigSchema, JobSchema } from '@objectstack/spec/system';

// AI protocols
import { AgentSchema, ModelRegistrySchema } from '@objectstack/spec/ai';

// Types (subpath imports — the root package does not export types)
import type { Field, ServiceObject, QueryAST } from '@objectstack/spec/data';
import type { View } from '@objectstack/spec/ui';

Declarative Endpoints (apis:)

Declared on the stack (defineStack({ apis })), live from protocol 17 — each entry is gated at publish and, once it passes, serves real traffic. Full contract: HTTP API → Declarative Endpoints.

Rule	Value
Path shape	/api/v1/apps/<manifest.namespace>/<subpath> — only the subpath is yours (ADR-0121 D1)
Namespace	must be declared explicitly as manifest.namespace; never derived from manifest.id (D2)
Types that execute	object_operation (needs objectParams.object + .operation) and flow (needs target). script / proxy are rejected at publish
authRequired	defaults to true — omitting it is safe. An explicit false is the only thing that opens anonymous access
authRequired: false	REQUIRES an armed budget, rateLimit: { enabled: true, windowMs, maxRequests } (ADR-0121 D6) — enabled itself defaults to false, so a budget without it meters nothing
cacheTtlSeconds	GET-only, applied to successful answers only (Cache-Control: private, max-age=<ttl>)

{/* os:check */}

import type { ApiEndpoint } from '@objectstack/spec/api';

// With `manifest: { namespace: 'acme', … }` on the same stack.
export const leadFeed: ApiEndpoint = {
  name: 'acme_lead_feed',
  path: '/api/v1/apps/acme/leads',   // /api/v1/apps/<namespace>/<subpath>
  method: 'GET',
  type: 'object_operation',
  // No `target` — object_operation is addressed by `objectParams` alone;
  // `target` is required (at publish) only for `type: 'flow'`.
  objectParams: { object: 'acme_lead', operation: 'find' },
  // `authRequired` omitted → defaults to true (a session is required).
  cacheTtlSeconds: 30,
};

Search Tips

• By Feature: "How do I model relationships?" → Field Protocol → lookup or master_detail types
• By Use Case: "Build a dashboard" → Dashboard Protocol
• By Layer: Data → Data Protocol, UI → UI Protocol, Runtime → System Protocol

Next Steps

**New to ObjectStack?** Start with the [Introduction](/docs/getting-started) to learn core concepts before diving into specific protocols.

• Protocol Reference Index - Full protocol documentation
• Data Modeling - Deep dive into data modeling
• UI Engine - UI development guide
• Contributing Guide - How to contribute to protocols