contract.mdx

title	Contract
description	Contract protocol schemas

{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

Standard Create Request

**Source:** `packages/spec/src/api/contract.zod.ts`

TypeScript Usage

import { ApiError, BaseResponse, BatchLoadingStrategy, BulkRequest, BulkResponse, CreateRequest, DataLoaderConfig, DeleteResponse, ExportRequest, IdRequest, ListRecordResponse, ModificationResult, QueryOptimizationConfig, RecordData, SingleRecordResponse, UpdateRequest } from '@objectstack/spec/api';
import type { ApiError, BaseResponse, BatchLoadingStrategy, BulkRequest, BulkResponse, CreateRequest, DataLoaderConfig, DeleteResponse, ExportRequest, IdRequest, ListRecordResponse, ModificationResult, QueryOptimizationConfig, RecordData, SingleRecordResponse, UpdateRequest } from '@objectstack/spec/api';

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

---

ApiError

Properties

Property	Type	Required	Description
code	string	✅	Error code (e.g. validation_error)
message	string	✅	Readable error message
category	string	optional	Error category (e.g. validation, authorization)
details	any	optional	Additional error context (e.g. field validation errors)
requestId	string	optional	Request ID for tracking

---

BaseResponse

Properties

Property	Type	Required	Description
success	boolean	✅	Operation success status
error	Object	optional	Error details if success is false
meta	Object	optional	Response metadata

---

BatchLoadingStrategy

Properties

Property	Type	Required	Description
strategy	Enum<'dataloader' | 'windowed' | 'prefetch'>	✅	Batch loading strategy type
windowMs	number	optional	Collection window duration in milliseconds (for windowed strategy)
prefetchDepth	integer	optional	Depth of relation prefetching (for prefetch strategy)
associationLoading	Enum<'lazy' | 'eager' | 'batch'>	✅	How to load related associations

---

BulkRequest

Properties

Property	Type	Required	Description
records	Record<string, any>[]	✅	Array of records to process
allOrNone	boolean	✅	If true, rollback entire transaction on any failure

---

BulkResponse

Properties

Property	Type	Required	Description
success	boolean	✅	Operation success status
error	Object	optional	Error details if success is false
meta	Object	optional	Response metadata
data	Object[]	✅	Results for each item in the batch

---

CreateRequest

Properties

Property	Type	Required	Description
data	Record<string, any>	✅	Record data to insert

---

DataLoaderConfig

Properties

Property	Type	Required	Description
maxBatchSize	integer	✅	Maximum number of keys per batch load
batchScheduleFn	Enum<'microtask' | 'timeout' | 'manual'>	✅	Scheduling strategy for collecting batch keys
cacheEnabled	boolean	✅	Enable per-request result caching
cacheKeyFn	string	optional	Name or identifier of the cache key function
cacheTtl	number	optional	Cache time-to-live in seconds (0 = no expiration)
coalesceRequests	boolean	✅	Deduplicate identical requests within a batch window
maxConcurrency	integer	optional	Maximum parallel batch requests

---

DeleteResponse

Properties

Property	Type	Required	Description
success	boolean	✅	Operation success status
error	Object	optional	Error details if success is false
meta	Object	optional	Response metadata
id	string	✅	ID of the deleted record

---

ExportRequest

Properties

Property	Type	Required	Description
object	string	✅	Object name (e.g. account)
fields	[__schema1](./__schema1)[]	optional	Fields to retrieve
where	[__schema2](./__schema2)	optional	Filtering criteria (WHERE)
search	Object	optional	Full-text search configuration ($search parameter)
orderBy	Object[]	optional	Sorting instructions (ORDER BY)
limit	number	optional	Max records to return (LIMIT)
offset	number	optional	Records to skip (OFFSET)
top	number	optional	Alias for limit (OData compatibility)
cursor	Record<string, any>	optional	Cursor for keyset pagination
joins	Object[]	optional	Explicit Table Joins
aggregations	Object[]	optional	Aggregation functions
groupBy	string | Object[]	optional	GROUP BY targets (strings or {field, dateGranularity?} objects for date bucketing)
having	[__schema2](./__schema2)	optional	HAVING clause for aggregation filtering
windowFunctions	Object[]	optional	Window functions with OVER clause
distinct	boolean	optional	SELECT DISTINCT flag
expand	Record<string, [__schema0](./__schema0)>	optional	Recursive relation loading map. Keys are lookup/master_detail field names; values are nested QueryAST objects that control select (fields) and filter (where, AND-merged with the batch $in), plus further expansion on the related object. The engine resolves expand via batch $in queries (driver-agnostic) with a default max depth of 3; per-parent limit/offset/orderBy are NOT applied on this path.

---

IdRequest

Properties

Property	Type	Required	Description
id	string	✅	Record ID

---

ListRecordResponse

Properties

Property	Type	Required	Description
success	boolean	✅	Operation success status
error	Object	optional	Error details if success is false
meta	Object	optional	Response metadata
data	Record<string, any>[]	✅	Array of matching records
pagination	Object	✅	Pagination info

---

ModificationResult

Properties

Property	Type	Required	Description
id	string	optional	Record ID if processed
success	boolean	✅
errors	Object[]	optional
index	number	optional	Index in original request
data	any	optional	Result data (e.g. created record)

---

QueryOptimizationConfig

Properties

Property	Type	Required	Description
preventNPlusOne	boolean	✅	Enable N+1 query detection and prevention
dataLoader	Object	optional	DataLoader batch loading configuration
batchStrategy	Object	optional	Batch loading strategy configuration
maxQueryDepth	integer	✅	Maximum depth for nested relation queries
queryComplexityLimit	number	optional	Maximum allowed query complexity score
enableQueryPlan	boolean	✅	Log query execution plans for debugging

---

---

SingleRecordResponse

Properties

Property	Type	Required	Description
success	boolean	✅	Operation success status
error	Object	optional	Error details if success is false
meta	Object	optional	Response metadata
data	Record<string, any>	✅	The requested or modified record

---

UpdateRequest

Properties

Property	Type	Required	Description
data	Record<string, any>	✅	Partial record data to update

---