Datasource

Driver Identifier Can be a built-in driver or a plugin-contributed driver (e.g., "com.vendor.snowflake").

Source: packages/spec/src/data/datasource.zod.ts

TypeScript Usage

import { DatasourceSchema, DriverDefinitionSchema, DriverType, ExternalDatasourceSettingsSchema, SchemaModeSchema } from '@objectstack/spec/data';
import type { Datasource, DriverDefinition, DriverType, ExternalDatasourceSettings, SchemaMode } from '@objectstack/spec/data';

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

Datasource

Properties

Property	Type	Required	Description
name	`string`	✅	Unique datasource identifier
label	`string`	optional	Display label
driver	`string`	✅	Underlying driver type
config	`Record<string, any>`	✅	Driver specific configuration
pool	`{ min: number; max: number; idleTimeoutMillis: number; connectionTimeoutMillis: number }`	optional	Connection pool settings
ssl	`{ enabled: boolean; rejectUnauthorized: boolean; ca?: string; cert?: string; … }`	optional	SSL/TLS configuration for secure database connections
description	`string`	optional	Internal description
active	`boolean`	optional (default: `true`)	Is datasource enabled
autoConnect	`boolean`	optional (default: `false`)	Force a live driver connection at boot even when managed + unrouted (ADR-0062 D2).
schemaMode	`Enum<'managed' \| 'external' \| 'validate-only'>`	optional (default: `"managed"`)	Schema ownership mode
external	`{ allowedSchemas?: string[]; allowWrites: boolean; validation: object; credentialsRef?: string; … }`	optional	External datasource settings: federation policy (schemaMode != "managed") plus the secrets-store credentials reference (valid in every schemaMode)
origin	`Enum<'code' \| 'runtime'>`	optional (default: `"code"`)	Datasource provenance (server-managed, read-only)
_lock	`Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>`	optional	Item-level lock — controls overlay & delete (ADR-0010).
_lockReason	`string`	optional	Human-readable reason shown when a write is refused by _lock.
_lockSource	`Enum<'artifact' \| 'package' \| 'env-forced'>`	optional	Layer that set _lock (artifact \| package \| env-forced).
_provenance	`Enum<'package' \| 'org' \| 'env-forced'>`	optional	Origin of the item (package \| org \| env-forced).
_packageId	`string`	optional	Owning package machine id.
_packageVersion	`string`	optional	Owning package version.
_lockDocsUrl	`string`	optional	Optional documentation link surfaced next to _lockReason.

Nested Shape: `Datasource.pool`

Property	Type	Required	Description
min	`number`	optional (default: `0`)	Minimum connections
max	`number`	optional (default: `10`)	Maximum connections
idleTimeoutMillis	`number`	optional (default: `30000`)	Idle timeout
connectionTimeoutMillis	`number`	optional (default: `3000`)	Connection establishment timeout

Nested Shape: `Datasource.ssl`

Property	Type	Required	Description
enabled	`boolean`	optional (default: `false`)	Enable SSL/TLS for database connection
rejectUnauthorized	`boolean`	optional (default: `true`)	Reject connections with invalid/self-signed certificates
ca	`string`	optional	CA certificate (PEM format or path to file)
cert	`string`	optional	Client certificate (PEM format or path to file)
key	`string`	optional	Client private key (PEM format or path to file)

Nested Shape: `Datasource.external`

Property	Type	Required	Description
allowedSchemas	`string[]`	optional	Whitelist of remote schemas/databases that may be exposed.
allowWrites	`boolean`	optional (default: `false`)	Global write gate. Individual objects must also opt in via object.external.writable.
validation	`{ onMismatch: Enum<'fail' \| 'warn' \| 'ignore'>; checkOnBoot: boolean; checkIntervalMs?: number }`	optional (default: `{"onMismatch":"fail","checkOnBoot":true}`)	Boot/drift validation policy
credentialsRef	`string`	optional	Reference into the secrets store; never inline credentials. Valid in every schemaMode — the one `external` key a managed datasource may carry.
queryTimeoutMs	`number`	optional (default: `30000`)	Hard cap on per-query execution time.

DriverDefinition

Properties

Property	Type	Required	Description
id	`string`	✅	Unique driver identifier (e.g. "postgres")
label	`string`	✅	Display label (e.g. "PostgreSQL")
description	`string`	optional
icon	`string`	optional
configSchema	`Record<string, any>`	✅	JSON Schema for connection configuration

DriverType

Underlying driver identifier

Type: string

ExternalDatasourceSettings

External datasource settings: federation policy (schemaMode != "managed") plus the secrets-store credentials reference (valid in every schemaMode)

Properties

Property	Type	Required	Description
allowedSchemas	`string[]`	optional	Whitelist of remote schemas/databases that may be exposed.
allowWrites	`boolean`	optional (default: `false`)	Global write gate. Individual objects must also opt in via object.external.writable.
validation	`{ onMismatch: Enum<'fail' \| 'warn' \| 'ignore'>; checkOnBoot: boolean; checkIntervalMs?: number }`	optional (default: `{"onMismatch":"fail","checkOnBoot":true}`)	Boot/drift validation policy
credentialsRef	`string`	optional	Reference into the secrets store; never inline credentials. Valid in every schemaMode — the one `external` key a managed datasource may carry.
queryTimeoutMs	`number`	optional (default: `30000`)	Hard cap on per-query execution time.

Nested Shape: `ExternalDatasourceSettings.validation`

Property	Type	Required	Description
onMismatch	`Enum<'fail' \| 'warn' \| 'ignore'>`	optional (default: `"fail"`)	What to do when a federated object diverges from the remote table.
checkOnBoot	`boolean`	optional (default: `true`)	Validate federated objects against the remote schema at boot.
checkIntervalMs	`number`	optional	Optional background drift-check interval in milliseconds.

SchemaMode

Schema ownership mode

Allowed Values

managed
external
validate-only

Datasource

On this page