Skip to content

Latest commit

 

History

History
855 lines (728 loc) · 49 KB

contract.mdx

File metadata and controls

855 lines (728 loc) · 49 KB
title Contract schema — API Protocol reference
navTitle Contract
description Contract schemas of the ObjectStack API Protocol: ApiError, BaseResponse and 14 more — each property with its type, default and a TypeScript example.

{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}

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

TypeScript Usage

import { ApiErrorSchema, BaseResponseSchema, BatchLoadingStrategySchema, BulkRequestSchema, BulkResponseSchema, CreateRequestSchema, DataLoaderConfigSchema, DeleteResponseSchema, ExportRequestSchema, IdRequestSchema, ListRecordResponseSchema, ModificationResultSchema, QueryOptimizationConfigSchema, RecordDataSchema, SingleRecordResponseSchema, UpdateRequestSchema } 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 = ApiErrorSchema.parse(data);

ApiError

Properties

Property Type Required Description
code Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | 'INVALID_FORMAT' | 'VALUE_TOO_LONG' | 'VALUE_TOO_SHORT' | 'VALUE_OUT_OF_RANGE' | … +363 more> ✅ Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages)
declaredCode string optional The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message string ✅ Readable error message
userMessage string optional Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message.
refusal true optional Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value.
category string optional Error category (e.g. validation, authorization)
httpStatus integer optional HTTP status of the response carrying this error
details any optional Additional error context (e.g. field validation errors)
requestId string optional Request ID for tracking

Allowed Values: ApiError.code

  • VALIDATION_ERROR
  • INVALID_FIELD
  • MISSING_REQUIRED_FIELD
  • INVALID_FORMAT
  • VALUE_TOO_LONG
  • VALUE_TOO_SHORT
  • VALUE_OUT_OF_RANGE
  • INVALID_REFERENCE
  • DUPLICATE_VALUE
  • INVALID_QUERY
  • INVALID_FILTER
  • INVALID_SORT
  • MAX_RECORDS_EXCEEDED
  • UNAUTHENTICATED
  • INVALID_CREDENTIALS
  • EXPIRED_TOKEN
  • INVALID_TOKEN
  • SESSION_EXPIRED
  • MFA_REQUIRED
  • EMAIL_NOT_VERIFIED
  • PERMISSION_DENIED
  • INSUFFICIENT_PRIVILEGES
  • FIELD_NOT_ACCESSIBLE
  • RECORD_NOT_ACCESSIBLE
  • LICENSE_REQUIRED
  • IP_RESTRICTED
  • TIME_RESTRICTED
  • RESOURCE_NOT_FOUND
  • OBJECT_NOT_FOUND
  • RECORD_NOT_FOUND
  • FIELD_NOT_FOUND
  • ENDPOINT_NOT_FOUND
  • RESOURCE_CONFLICT
  • CONCURRENT_MODIFICATION
  • DELETE_RESTRICTED
  • DUPLICATE_RECORD
  • LOCK_CONFLICT
  • METHOD_NOT_ALLOWED
  • PRECONDITION_REQUIRED
  • RATE_LIMIT_EXCEEDED
  • QUOTA_EXCEEDED
  • INTERNAL_ERROR
  • DATABASE_ERROR
  • TIMEOUT
  • SERVICE_UNAVAILABLE
  • NOT_IMPLEMENTED
  • EXTERNAL_SERVICE_ERROR
  • INTEGRATION_ERROR
  • WEBHOOK_DELIVERY_FAILED
  • ACCESS_UPGRADE_CONFIRMATION_REQUIRED
  • ACCOUNT_LOCKED
  • ACTION_CONFIRMATION_REQUIRED
  • ACTION_DISABLED
  • ALREADY_REVERTED
  • AMBIGUOUS_MATCH
  • ANALYTICS_DATE_RANGE_UNRECOGNIZED
  • ANALYTICS_QUERY_FAILED
  • API_KEY_EXPIRED
  • API_KEY_EXPIRY_TOO_LONG
  • API_KEY_INACTIVE
  • API_KEY_REVOKED
  • APPROVAL_ACTIONS_FAILED
  • APPROVAL_APPROVE_FAILED
  • APPROVAL_COMMENT_FAILED
  • APPROVAL_REASSIGN_FAILED
  • APPROVAL_RECALL_FAILED
  • APPROVAL_REJECT_FAILED
  • APPROVAL_REMIND_FAILED
  • APPROVAL_REQUEST_GET_FAILED
  • APPROVAL_REQUEST_INFO_FAILED
  • APPROVAL_REQUEST_LIST_FAILED
  • APPROVAL_RESUBMIT_FAILED
  • APPROVAL_REVISE_FAILED
  • ASYNC_NOT_SUPPORTED
  • ATTACHMENT_DELETE_DENIED
  • ATTACHMENT_DOWNLOAD_DENIED
  • ATTACHMENT_PARENT_ACCESS
  • AUDIENCE_NOT_ALLOWED
  • AUDIT_TYPE_NOT_CANONICAL
  • AUTH_CONFIG_ERROR
  • AUTH_REQUIRED
  • AUTOMATION_UNSCOPED_RUN_DATA_ACCESS
  • BATCH_ABORTED
  • BATCH_NOT_ATOMIC
  • BATCH_TOO_LARGE
  • BATCH_UNRESOLVED_REF
  • BLANK_MATCH_KEY
  • CLONE_DISABLED
  • CLOUD_FETCH_FAILED
  • CLOUD_UNCONFIGURED
  • COMMIT_NOT_FOUND
  • CONCURRENT_UPDATE
  • CONFLICT
  • CONFLICTING_MAPPING
  • CONNECTOR_CREDENTIAL_REJECTED
  • CONNECTOR_UPSTREAM_CHANGED
  • CONNECTOR_UPSTREAM_UNAVAILABLE
  • CREATE_FAILED
  • CUBE_NOT_FOUND
  • DATASET_INVALID
  • DATASOURCE_ADMIN_ERROR
  • DEFAULT_RECORD_PAGE_CONFLICT
  • DELEGABLE_SCOPE_FAILED
  • DELEGATION_SCOPE_VIOLATION
  • DELETE_HOOK_RESULT_NOT_WRITE_SHAPE
  • DELIVERY_NEVER_SENT
  • DELIVERY_NOT_ELIGIBLE
  • DEPENDENCY_MISSING
  • DESTRUCTIVE_CHANGE
  • DEVICE_CODE_FAILED
  • DOMAIN_VERIFICATION_DISABLED
  • DOMAIN_VERIFICATION_FAILED
  • DRIVER_UNAVAILABLE
  • DUPLICATE_ARTIFACT_OBJECT_NAME
  • DUPLICATE_ARTIFACT_PACKAGE
  • DUPLICATE_MATCH_KEY
  • DUPLICATE_REQUEST
  • DUPLICATE_SOURCE_NOT_A_BASE
  • ELIGIBILITY_UNEVALUABLE
  • EMAIL_DOMAIN_NOT_ALLOWED
  • EMAIL_SEND_FAILED
  • EMAIL_SERVICE_REQUIRED
  • ENQUEUE_FAILED
  • ENVIRONMENT_BIND_FAILED
  • ENVIRONMENT_NOT_FOUND
  • ENV_ACCESS_DENIED
  • ERR_AUTONUMBER_COLLISION
  • ERR_BULK_RESULT_MISMATCH
  • ERR_CROSS_DATASOURCE_TRANSACTION_WRITE
  • ERR_CURRENCY_CODE_REQUIRED
  • ERR_DATASOURCE_UNAVAILABLE
  • ERR_DRIVER_CONNECT
  • ERR_EXCHANGE_RATE_MISSING
  • ERR_FILE_CONSTRAINT
  • ERR_FILE_REFERENCE_COPY
  • ERR_HOME_CURRENCY_UNSET
  • ERR_HOOK_TARGET_REBIND
  • ERR_READONLY_FIELD_REJECTED
  • ERR_SUMMARY_RECOMPUTE
  • ERR_SYSTEM_WRITE_ORGANIZATION_REQUIRED
  • ERR_TRANSACTION_UNSUPPORTED
  • EXECUTION_ERROR
  • EXPIRED_OR_REVOKED
  • EXPIRY_IN_PAST
  • EXPIRY_TOO_LONG
  • EXPLAIN_FAILED
  • EXPORT_NOT_PERMITTED
  • EXTERNAL_DATASOURCE_ERROR
  • EXTERNAL_IMPORT_ERROR
  • EXTERNAL_ROW_CAP_EXCEEDED
  • EXTERNAL_SCHEMA_MISMATCH
  • EXTERNAL_SCHEMA_MODE_VIOLATION
  • EXTERNAL_WRITE_FORBIDDEN
  • EXTERNAL_WRITE_REFUSED
  • FEEDS_DISABLED
  • FIELD_VISIBILITY_UNRESOLVED
  • FILES_DISABLED
  • FILE_DOWNLOAD_DENIED
  • FILE_FIELD_BULK_WRITE_REFUSED
  • FILE_NOT_FOUND
  • FILTER_TOKEN_UNKNOWN
  • FILTER_TOKEN_UNRESOLVED
  • FIND_HOOK_RESULT_NOT_ARRAY
  • FIND_ONE_HOOK_RESULT_NOT_RECORD
  • FLOW_DISABLED
  • FLOW_FAILED
  • FLOW_INPUT_SCHEMA_INVALID
  • FLOW_NO_START_NODE
  • FORBIDDEN
  • FORM_NOT_FOUND
  • FORM_RESOLVE_FAILED
  • HOOK_ABORTED
  • HOOK_UNSCOPED_DATA_ACCESS
  • IMPORT_JOB_CREATE_FAILED
  • IMPORT_ROW_FAILED
  • INSTALL_MODE_NOT_PERMITTED
  • INTERNAL
  • INVALID_ARTIFACT_PACKAGES
  • INVALID_ARTIFACT_PACKAGE_ENTRY
  • INVALID_EMAIL
  • INVALID_EXPIRY
  • INVALID_METADATA
  • INVALID_OR_EXPIRED
  • INVALID_PHONE
  • INVALID_REQUEST
  • INVALID_RESUME_TOKEN
  • INVALID_SCREEN_INPUT
  • INVALID_SIGNAL
  • INVALID_SIGNATURE
  • INVALID_STATE
  • INVITE_EMAIL_FAILED
  • INVITE_ISSUER_MEMBER_ONLY
  • INVITE_ISSUER_UNVERIFIED
  • INVITE_PLACEMENT_OUTSIDE_ISSUER_SCOPE
  • INVITE_PLACEMENT_UNSUPPORTED
  • INVITE_REQUIRES_EMAIL
  • INVITE_ROLE_ABOVE_ISSUER
  • INVITE_SMS_FAILED
  • IP_NOT_ALLOWED
  • ITEM_LOCKED
  • LAST_LOCAL_CREDENTIAL
  • LEGACY_ORGANIZATION_ROWS_UNREADABLE
  • MANIFEST_CONFLICT
  • MAPPING_FORMAT_MISMATCH
  • MAPPING_FORMAT_UNSUPPORTED
  • MAPPING_NOT_FOUND
  • MAPPING_TARGET_MISMATCH
  • MARKETPLACE_PROXY_FAILED
  • MARKETPLACE_STORAGE_FAILED
  • MARKETPLACE_UNAVAILABLE
  • MEMORY_MULTI_TENANT_UNSUPPORTED
  • METADATA_BRANCH
  • METADATA_CONFLICT
  • METADATA_NOT_FOUND
  • METADATA_SCHEMA_INVALID
  • MIXED_ARTIFACT_COLLECTION_SHAPE
  • MONGODB_MULTI_TENANT_UNSUPPORTED
  • MULTI_UPDATE_HOOK_KEY_DIVERGENCE
  • NAMESPACE_CONFLICT
  • NAMESPACE_PREFIX
  • NEEDS_PASSWORD
  • NODE_FAILURE
  • NOTHING_TO_PURGE
  • NOT_ATTEMPTED
  • NOT_COMPENSABLE
  • NOT_CREATABLE
  • NOT_FOUND
  • NOT_OVERRIDABLE
  • NOT_UNDOABLE
  • NO_ACTIVE_ORGANIZATION
  • NO_DRAFT
  • NO_EXECUTOR
  • NO_IDENTITY
  • NO_MATCH
  • NO_PENDING_VERIFICATION
  • NO_SUCH_RUN
  • OAUTH_REGISTER_FAILED
  • OBJECT_API_DISABLED
  • OBJECT_API_METHOD_NOT_ALLOWED
  • OBJECT_OVERLAY_PACKAGE_MISMATCH
  • OBJECT_OWNERSHIP_CONFLICT
  • OBJECT_PACKAGE_DISABLED
  • OPENAPI_UNAVAILABLE
  • ORGANIZATION_CREATION_DISABLED
  • ORGANIZATION_OWNERSHIP_MIGRATION_REQUIRED
  • ORGANIZATION_SLUG_LOCKED_BY_ACTIVE_ENVIRONMENTS
  • OS_PROTOCOL_INCOMPATIBLE
  • PACKAGE_DELETE_FAILED
  • PACKAGE_DELETE_PARTIAL
  • PACKAGE_DISABLE_RESTRICTED_BY_VALIDATION_RULE
  • PACKAGE_MANIFEST_INVALID
  • PACKAGE_PUBLISH_FAILED
  • PASSWORD_ALREADY_SET
  • PASSWORD_EXPIRED
  • PASSWORD_POLICY_VIOLATION
  • PASSWORD_RESET_REQUIRED
  • PASSWORD_REUSE
  • PAYLOAD_TOO_LARGE
  • PERMISSION_NOT_ALLOWED
  • PHONE_NOT_ENABLED
  • PLAN_CHANGED
  • PLUGIN_CONTRACT_VIOLATION
  • PLUGIN_INSTALL_FAILED
  • PLUGIN_MANIFEST_INVALID
  • PLUGIN_REGISTER_FAILED
  • PLUGIN_UI_REQUIRED_KEY_MISSING
  • PREFLIGHT_FAILED
  • PROJECT_MEMBERSHIP_REQUIRED
  • PROJECT_NOT_FOUND
  • PROJECT_PROVISIONING
  • PROJECT_PROVISIONING_FAILED
  • QUERY_OBJECT_MISMATCH
  • QUERY_ROW_BUDGET_EXCEEDED
  • QUEUE_NOT_FOUND
  • RAW_SQL_UNSUPPORTED
  • READ_BACK_FAILED
  • READ_SCOPE_COMPILE_FAILED
  • RECORD_GONE
  • RECORD_LOCKED
  • RECORD_NOT_ELIGIBLE
  • REGISTRY_TYPE_NOT_CANONICAL
  • REQUEST_NOT_FOUND
  • RESEED_NO_ROWS
  • RESEED_SKIPPED
  • RESTORE_PACKAGE_UNINSTALLED
  • RESTORE_PARENT_IN_RECYCLE_BIN
  • RESTORE_PARENT_PURGED
  • RESTORE_UNIQUE_VALUE_TAKEN
  • RESUME_CHILD_PENDING
  • RESUME_FAILED
  • RESUME_IN_PROGRESS
  • RESUME_TARGET_LOST
  • ROLE_NOT_FOUND
  • ROLLED_BACK
  • ROUTE_NOT_FOUND
  • RULE_DEFINE_FAILED
  • RULE_DELETE_FAILED
  • RULE_EVALUATE_FAILED
  • RULE_GET_FAILED
  • RULE_LIST_FAILED
  • RULE_NOT_FOUND
  • RUN_NOT_FOUND
  • SAML_REGISTER_FAILED
  • SCHEMA_UPGRADE_CONFIRMATION_REQUIRED
  • SELF_REGISTRATION_CLOSED
  • SERVICE_NOT_REGISTERED
  • SETTINGS_ACTION_FAILED
  • SETTINGS_CRYPTO_UNAVAILABLE
  • SETTINGS_ENGINE_NOT_BOUND
  • SETTINGS_FORBIDDEN
  • SETTINGS_LOCKED
  • SETTINGS_UNKNOWN_KEY
  • SETTINGS_UNKNOWN_NAMESPACE
  • SETTINGS_VALIDATION
  • SHARES_LIST_FAILED
  • SHARE_GRANT_FAILED
  • SHARE_REVOKE_FAILED
  • SHARING_NOT_ENABLED
  • SIGN_IN_REQUIRED
  • SMS_SERVICE_REQUIRED
  • SQL_DIALECT_EMISSION_UNSUPPORTED
  • SSO_REGISTER_FAILED
  • SSO_REGISTER_FORBIDDEN
  • STACK_CAPABILITY_UNKNOWN
  • STACK_COMPOSE_ACTION_KEY_COLLISION
  • STACK_COMPOSE_COLLECTION_CONFLICT
  • STACK_COMPOSE_FUNCTIONS_SHAPE_CONFLICT
  • STACK_COMPOSE_FUNCTION_CONFLICT
  • STACK_COMPOSE_KEY_CONFLICT
  • STACK_COMPOSE_OBJECT_CONFLICT
  • STACK_CROSS_REFERENCE_INVALID
  • STACK_HIERARCHY_SCOPE_CAPABILITY_REQUIRED
  • STACK_NAMESPACE_PREFIX_INVALID
  • STACK_PROVENANCE_MISSING
  • STACK_SCHEMA_INVALID
  • STACK_SINGLE_APP_VIOLATION
  • STACK_TRIGGER_CAPABILITY_REQUIRED
  • STACK_UNMANAGED_INSTALL_UNCOPYABLE
  • STACK_WEBHOOK_CAPABILITY_REQUIRED
  • STORED_TYPE_NOT_CANONICAL
  • STORE_UNAVAILABLE
  • SUGGESTION_CONFIRM_FAILED
  • SUGGESTION_DISMISS_FAILED
  • SUGGESTION_LIST_FAILED
  • SUGGESTION_NOT_FOUND
  • SUGGESTION_STATE
  • SUMMARY_RECOMPUTE_FAILED
  • THROTTLED
  • UNAUTHORIZED
  • UNIQUE_SCOPE_CONFIRMATION_REQUIRED
  • UNIQUE_VIOLATION
  • UNKNOWN_KEY
  • UNKNOWN_NAMESPACE
  • UNMANAGED_INSTALL_UNCOPYABLE
  • UNMANAGED_INSTALL_WALLED_POSTURE
  • UNSUPPORTED
  • UNSUPPORTED_QUERY_PARAM
  • UNSUPPORTED_TRANSFORM
  • UPDATE_HOOK_RESULT_NOT_WRITE_SHAPE
  • UPDATE_ID_MISMATCH
  • UPLOAD_SESSION_EXPIRED
  • UPLOAD_SESSION_NOT_FOUND
  • USER_ALREADY_EXISTS
  • USER_ALREADY_EXISTS_USE_ANOTHER_EMAIL
  • VALIDATION_FAILED
  • VERSION_NOT_FOUND
  • VERSION_NOT_RESTORABLE
  • WALLED_MEMBERSHIP_POLICY_UNDECLARED
  • WRITABLE_PACKAGE_REQUIRED
  • WRONG_PASSWORD

BaseResponse

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } optional Error details if success is false
meta { timestamp: string; duration?: integer; requestId?: string; traceId?: string } optional Response metadata

Nested Shape: BaseResponse.error

Property Type Required Description
code Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> ✅ Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages)
declaredCode string optional The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message string ✅ Readable error message
userMessage string optional Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message.
refusal true optional Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value.
category string optional Error category (e.g. validation, authorization)
httpStatus integer optional HTTP status of the response carrying this error
details any optional Additional error context (e.g. field validation errors)
requestId string optional Request ID for tracking

Nested Shape: BaseResponse.meta

Property Type Required Description
timestamp string ✅
duration integer optional Server-side processing duration in milliseconds
requestId string optional
traceId string optional

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'> optional (default: "batch") How to load related associations

BulkRequest

Properties

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

BulkResponse

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } optional Error details if success is false
meta { timestamp: string; duration?: integer; requestId?: string; traceId?: string } optional Response metadata
data { id?: string; success: boolean; errors?: object[]; index?: number; … }[] ✅ Results for each item in the batch

Nested Shape: BulkResponse.error

Property Type Required Description
code Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> ✅ Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages)
declaredCode string optional The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message string ✅ Readable error message
userMessage string optional Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message.
refusal true optional Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value.
category string optional Error category (e.g. validation, authorization)
httpStatus integer optional HTTP status of the response carrying this error
details any optional Additional error context (e.g. field validation errors)
requestId string optional Request ID for tracking

Nested Shape: BulkResponse.meta

Property Type Required Description
timestamp string ✅
duration integer optional Server-side processing duration in milliseconds
requestId string optional
traceId string optional

Nested Shape: BulkResponse.data[number]

Property Type Required Description
id string optional Record ID if processed
success boolean ✅
errors { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … }[] optional
index number optional Index in original request
data any optional Result data (e.g. created record)

CreateRequest

Properties

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

DataLoaderConfig

Properties

Property Type Required Description
maxBatchSize integer optional (default: 100) Maximum number of keys per batch load
batchScheduleFn Enum<'microtask' | 'timeout' | 'manual'> optional (default: "microtask") Scheduling strategy for collecting batch keys
cacheEnabled boolean optional (default: true) Enable per-request result caching
cacheKeyFn string optional Name or identifier of the cache key function
cacheTtlSeconds number optional Cache time-to-live in seconds (0 = no expiration)
cacheTtl never optional [REMOVED] DataLoaderConfig.cacheTtl was renamed to cacheTtlSeconds in @objectstack/spec 17 — the unit of a duration-shaped number lives in the key name, not only in the describe prose. Rename the key to cacheTtlSeconds; the value (seconds) is unchanged.
coalesceRequests boolean optional (default: true) 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 { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } optional Error details if success is false
meta { timestamp: string; duration?: integer; requestId?: string; traceId?: string } optional Response metadata
id string ✅ ID of the deleted record

Nested Shape: DeleteResponse.error

Property Type Required Description
code Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> ✅ Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages)
declaredCode string optional The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message string ✅ Readable error message
userMessage string optional Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message.
refusal true optional Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value.
category string optional Error category (e.g. validation, authorization)
httpStatus integer optional HTTP status of the response carrying this error
details any optional Additional error context (e.g. field validation errors)
requestId string optional Request ID for tracking

Nested Shape: DeleteResponse.meta

Property Type Required Description
timestamp string ✅
duration integer optional Server-side processing duration in milliseconds
requestId string optional
traceId string optional

ExportRequest

Properties

Property Type Required Description
object string ✅ Object name (e.g. account)
fields string[] optional Fields to retrieve — names of the queried object's OWN columns, at least one: omit fields to read every column, because an empty list or a blank name is refused rather than read as every column. A dotted path (owner.name) is not a projection: no driver resolves one, and the ingress refuses it with 400 INVALID_FIELD. Related data is read with expand, whose nested QueryAST both filters (where) and selects (fields) the related record's columns. The projection must RETAIN the foreign-key column: fields: ['title'] with expand: 'project_id' resolves nothing, because the relation is carried by that key — add 'project_id' and it works. Where the value is wanted on the queried object itself, denormalise it onto that object (a stored field, written when the source changes), the same remedy the sort axis prescribes.
where any optional Filtering criteria (WHERE)
search string | { query: string; fields?: string[]; fuzzy?: boolean; operator?: Enum<'and' | 'or'>; … } optional Full-text search — the query text (canonical, ADR-0061 D1), or a structured FullTextSearch configuration
searchFields string[] optional Narrow the search to these fields (server-intersected with the allowed searchable set — can only narrow, never widen; ADR-0061 D1) — at least one field name; a value naming no field (blank, only commas and spaces, or an empty list) is refused
orderBy { field: string; order?: Enum<'asc' | 'desc'> }[] 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 never optional [REMOVED] query.cursor was removed in @objectstack/spec 17 (ADR-0049) — no driver ever implemented keyset pagination, so the cursor was accepted and ignored and every page came back identical (a caller looping "until hasMore is false" never terminates). Delete the key; QueryBuilder.cursor() was removed with it. Express the keyset as an ordinary where predicate on your sort key — where: { created_at: { $gt: last.created_at } } with the matching orderBy — which every driver executes with canonicalised comparands. A first-class cursor, if ever built, will be a response-minted opaque token, not this caller-built record.
joins never optional [REMOVED] query.joins was removed in @objectstack/spec 17 (ADR-0049) — no engine or driver ever read it: a query carrying joins behaved exactly as if the key were absent, while its name squatted on the reserved REST parameter set. Delete the key. Related records are read through expand — expand: { owner_id: { object: 'user', fields: ['name'] } } — which the engine resolves via batch $in queries, and whose nested query selects the related record's own columns. Keep the foreign key in your own projection (fields: ['title', 'owner_id']): the relation is carried by that column, so projecting it away leaves expansion nothing to resolve. A dotted fields path is NOT a replacement — no driver ever resolved one and the ingress refuses it (400 INVALID_FIELD).
aggregations { function: Enum<'count' | 'sum' | 'avg' | 'min' | 'max' | 'count_distinct'>; field?: string; alias: string; filter?: any }[] optional Aggregation functions
groupBy (string | { field: string; dateGranularity?: Enum<'day' | 'week' | 'month' | 'quarter' | 'year'>; alias?: string })[] optional GROUP BY targets (strings or {field, dateGranularity?} objects for date bucketing)
having any optional HAVING — filter over the AGGREGATED rows (aggregation aliases + groupBy projections); applied engine-side after aggregation
windowFunctions never optional [REMOVED] query.windowFunctions was removed in @objectstack/spec 17 (ADR-0049) — find() never applied it: no engine or driver read the key on the query path, so every OVER clause it declared was silently dropped. Delete the key. Window functions are a SQL-driver capability behind SqlDriver.findWithWindowFunctions(object, query) (embedder-level; not on the IDataDriver contract or the REST surface); request-level analytics are aggregations + groupBy.
distinct never optional [REMOVED] query.distinct was removed in @objectstack/spec 17 (ADR-0049 / ADR-0078) — no driver ever rendered SELECT DISTINCT; the flag's only observable effect was MIS-WIRED: the REST list path treated a distinct query as not countable and silently degraded total/hasMore to a page-local estimate while still returning duplicate rows. Delete the key; QueryBuilder.distinct() was removed with it, and the count suppression is gone (total is truthful again). For unique values of one column use the SQL/memory drivers' distinct(object, field) door; for unique combinations, groupBy; for a deduplicated count, the count_distinct aggregation.
expand Record<string, { object: string; fields?: string[]; where?: any; search?: string | object; … }> 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.

Nested Shape: ExportRequest.search

Property Type Required Description
query string ✅ Search query text
fields string[] optional Fields to search in (if not specified, searches all text fields) — at least one field name; a value naming no field (blank, only commas and spaces, or an empty list) is refused
fuzzy boolean optional (default: false) [EXPERIMENTAL — not enforced] Fuzzy matching (tolerate typos). The ADR-0061 expansion reads only query + fields; no executor receives this flag.
operator Enum<'and' | 'or'> optional (default: "or") [EXPERIMENTAL — not enforced] Logical operator between terms. The ADR-0061 expansion applies its own term semantics; no executor receives this flag.
boost Record<string, number> optional [EXPERIMENTAL — not enforced] Field-specific relevance boosting (field name -> boost factor). No executor scores results.
minScore number optional [EXPERIMENTAL — not enforced] Minimum relevance score threshold. No executor scores results.
language string optional [EXPERIMENTAL — not enforced] Language for text analysis (e.g., "en", "zh", "es"). No executor selects an analyzer.
highlight boolean optional (default: false) [EXPERIMENTAL — not enforced] Search result highlighting. No executor emits highlights.

Nested Shape: ExportRequest.aggregations[number]

Property Type Required Description
function Enum<'count' | 'sum' | 'avg' | 'min' | 'max' | 'count_distinct'> ✅ Aggregation function
field string optional Field to aggregate (optional for COUNT(*))
alias string ✅ Result column alias
distinct never optional [REMOVED] query.aggregations[].distinct was removed in @objectstack/spec 17 (ADR-0049) — exactly ONE of the six faces that read an aggregation honoured it. The objectql in-memory fallback deduplicated the values before applying the function, while driver-sql, driver-turso, driver-mongodb, driver-memory and the service-analytics SQL builder all ignored it — so { function: 'sum', field: 'amount', distinct: true } answered a DEDUPLICATED sum when the engine fell back in memory and an ordinary sum on every SQL datasource: one query, two numbers, chosen by which backend happened to serve it. Both answers are plausible, so nothing surfaced the divergence. Delete the key. For a deduplicated COUNT the live spelling is the count_distinct aggregation function, which every SQL face compiles to COUNT(DISTINCT field) and the in-memory fallback computes identically. SUM(DISTINCT …) / AVG(DISTINCT …) get no replacement: no backend ever computed them here, and a per-row measure that needs deduplicating is a modelling problem to fix in the data, not a flag on the read.
filter any optional Per-aggregation filter (SQL FILTER (WHERE …) semantics): narrows the source rows THIS aggregation reads, leaving sibling aggregations unfiltered. Enforced by engine.aggregate: lowered in memory for drivers without native conditional aggregation; a driver reached directly refuses rather than silently dropping it.

Nested Shape: ExportRequest.groupBy[number]

Property Type Required Description
field string ✅ Field to group by
dateGranularity Enum<'day' | 'week' | 'month' | 'quarter' | 'year'> optional Bucket date values into uniform periods (day/week/month/quarter/year)
alias string optional Alias for the projected group value

Nested Shape: ExportRequest.expand[string]

Property Type Required Description
object string ✅ Object name (e.g. account)
fields string[] optional Fields to retrieve — names of the queried object's OWN columns, at least one: omit fields to read every column, because an empty list or a blank name is refused rather than read as every column. A dotted path (owner.name) is not a projection: no driver resolves one, and the ingress refuses it with 400 INVALID_FIELD. Related data is read with expand, whose nested QueryAST both filters (where) and selects (fields) the related record's columns. The projection must RETAIN the foreign-key column: fields: ['title'] with expand: 'project_id' resolves nothing, because the relation is carried by that key — add 'project_id' and it works. Where the value is wanted on the queried object itself, denormalise it onto that object (a stored field, written when the source changes), the same remedy the sort axis prescribes.
where any optional Filtering criteria (WHERE)
search string | { query: string; fields?: string[]; fuzzy?: boolean; operator?: Enum<'and' | 'or'>; … } optional Full-text search — the query text (canonical, ADR-0061 D1), or a structured FullTextSearch configuration
searchFields string[] optional Narrow the search to these fields (server-intersected with the allowed searchable set — can only narrow, never widen; ADR-0061 D1) — at least one field name; a value naming no field (blank, only commas and spaces, or an empty list) is refused
orderBy { field: string; order?: Enum<'asc' | 'desc'> }[] 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 never optional [REMOVED] query.cursor was removed in @objectstack/spec 17 (ADR-0049) — no driver ever implemented keyset pagination, so the cursor was accepted and ignored and every page came back identical (a caller looping "until hasMore is false" never terminates). Delete the key; QueryBuilder.cursor() was removed with it. Express the keyset as an ordinary where predicate on your sort key — where: { created_at: { $gt: last.created_at } } with the matching orderBy — which every driver executes with canonicalised comparands. A first-class cursor, if ever built, will be a response-minted opaque token, not this caller-built record.
joins never optional [REMOVED] query.joins was removed in @objectstack/spec 17 (ADR-0049) — no engine or driver ever read it: a query carrying joins behaved exactly as if the key were absent, while its name squatted on the reserved REST parameter set. Delete the key. Related records are read through expand — expand: { owner_id: { object: 'user', fields: ['name'] } } — which the engine resolves via batch $in queries, and whose nested query selects the related record's own columns. Keep the foreign key in your own projection (fields: ['title', 'owner_id']): the relation is carried by that column, so projecting it away leaves expansion nothing to resolve. A dotted fields path is NOT a replacement — no driver ever resolved one and the ingress refuses it (400 INVALID_FIELD).
aggregations { function: Enum<'count' | 'sum' | 'avg' | 'min' | 'max' | 'count_distinct'>; field?: string; alias: string; filter?: any }[] optional Aggregation functions
groupBy (string | { field: string; dateGranularity?: Enum<'day' | 'week' | 'month' | 'quarter' | 'year'>; alias?: string })[] optional GROUP BY targets (strings or {field, dateGranularity?} objects for date bucketing)
having any optional HAVING — filter over the AGGREGATED rows (aggregation aliases + groupBy projections); applied engine-side after aggregation
windowFunctions never optional [REMOVED] query.windowFunctions was removed in @objectstack/spec 17 (ADR-0049) — find() never applied it: no engine or driver read the key on the query path, so every OVER clause it declared was silently dropped. Delete the key. Window functions are a SQL-driver capability behind SqlDriver.findWithWindowFunctions(object, query) (embedder-level; not on the IDataDriver contract or the REST surface); request-level analytics are aggregations + groupBy.
distinct never optional [REMOVED] query.distinct was removed in @objectstack/spec 17 (ADR-0049 / ADR-0078) — no driver ever rendered SELECT DISTINCT; the flag's only observable effect was MIS-WIRED: the REST list path treated a distinct query as not countable and silently degraded total/hasMore to a page-local estimate while still returning duplicate rows. Delete the key; QueryBuilder.distinct() was removed with it, and the count suppression is gone (total is truthful again). For unique values of one column use the SQL/memory drivers' distinct(object, field) door; for unique combinations, groupBy; for a deduplicated count, the count_distinct aggregation.
expand Record<string, { object: string; fields?: string[]; where?: any; search?: string | object; … }> 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 { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } optional Error details if success is false
meta { timestamp: string; duration?: integer; requestId?: string; traceId?: string } optional Response metadata
data Record<string, any>[] ✅ Array of matching records
pagination { total?: number; limit?: number; offset?: number; cursor?: string; … } ✅ Pagination info

Nested Shape: ListRecordResponse.error

Property Type Required Description
code Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> ✅ Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages)
declaredCode string optional The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message string ✅ Readable error message
userMessage string optional Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message.
refusal true optional Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value.
category string optional Error category (e.g. validation, authorization)
httpStatus integer optional HTTP status of the response carrying this error
details any optional Additional error context (e.g. field validation errors)
requestId string optional Request ID for tracking

Nested Shape: ListRecordResponse.meta

Property Type Required Description
timestamp string ✅
duration integer optional Server-side processing duration in milliseconds
requestId string optional
traceId string optional

Nested Shape: ListRecordResponse.pagination

Property Type Required Description
total number optional Total matching records count
limit number optional Page size
offset number optional Page offset
cursor string optional Cursor for next page
nextCursor string optional Next cursor for pagination
hasMore boolean ✅ Are there more pages?

ModificationResult

Properties

Property Type Required Description
id string optional Record ID if processed
success boolean ✅
errors { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … }[] optional
index number optional Index in original request
data any optional Result data (e.g. created record)

Nested Shape: ModificationResult.errors[number]

Property Type Required Description
code Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> ✅ Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages)
declaredCode string optional The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message string ✅ Readable error message
userMessage string optional Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message.
refusal true optional Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value.
category string optional Error category (e.g. validation, authorization)
httpStatus integer optional HTTP status of the response carrying this error
details any optional Additional error context (e.g. field validation errors)
requestId string optional Request ID for tracking

QueryOptimizationConfig

Properties

Property Type Required Description
preventNPlusOne boolean ✅ Enable N+1 query detection and prevention
dataLoader { maxBatchSize?: integer; batchScheduleFn?: Enum<'microtask' | 'timeout' | 'manual'>; cacheEnabled?: boolean; cacheKeyFn?: string; … } optional DataLoader batch loading configuration
batchStrategy { strategy: Enum<'dataloader' | 'windowed' | 'prefetch'>; windowMs?: number; prefetchDepth?: integer; associationLoading?: Enum<'lazy' | 'eager' | 'batch'> } optional Batch loading strategy configuration
maxQueryDepth integer ✅ Maximum depth for nested relation queries
queryComplexityLimit number optional Maximum allowed query complexity score
enableQueryPlan boolean optional (default: false) Log query execution plans for debugging

Nested Shape: QueryOptimizationConfig.dataLoader

Property Type Required Description
maxBatchSize integer optional (default: 100) Maximum number of keys per batch load
batchScheduleFn Enum<'microtask' | 'timeout' | 'manual'> optional (default: "microtask") Scheduling strategy for collecting batch keys
cacheEnabled boolean optional (default: true) Enable per-request result caching
cacheKeyFn string optional Name or identifier of the cache key function
cacheTtlSeconds number optional Cache time-to-live in seconds (0 = no expiration)
cacheTtl never optional [REMOVED] DataLoaderConfig.cacheTtl was renamed to cacheTtlSeconds in @objectstack/spec 17 — the unit of a duration-shaped number lives in the key name, not only in the describe prose. Rename the key to cacheTtlSeconds; the value (seconds) is unchanged.
coalesceRequests boolean optional (default: true) Deduplicate identical requests within a batch window
maxConcurrency integer optional Maximum parallel batch requests

Nested Shape: QueryOptimizationConfig.batchStrategy

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'> optional (default: "batch") How to load related associations

RecordData

Key-value map of record data

Type: Record<string, any>


SingleRecordResponse

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } optional Error details if success is false
meta { timestamp: string; duration?: integer; requestId?: string; traceId?: string } optional Response metadata
data Record<string, any> ✅ The requested or modified record

Nested Shape: SingleRecordResponse.error

Property Type Required Description
code Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> ✅ Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages)
declaredCode string optional The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message string ✅ Readable error message
userMessage string optional Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message.
refusal true optional Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value.
category string optional Error category (e.g. validation, authorization)
httpStatus integer optional HTTP status of the response carrying this error
details any optional Additional error context (e.g. field validation errors)
requestId string optional Request ID for tracking

Nested Shape: SingleRecordResponse.meta

Property Type Required Description
timestamp string ✅
duration integer optional Server-side processing duration in milliseconds
requestId string optional
traceId string optional

UpdateRequest

Properties

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