External Catalog External Catalog protocol schemas
ExternalCatalog — cached remote-schema snapshot for a federated datasource
(ADR-0015 §4.3).
Introspecting a mature warehouse on every boot is expensive, so the
IExternalDatasourceService.refreshCatalog persists a snapshot of the
remote tables/columns as an external_catalog metadata record. The
boot-validation gate (Gate 2) and Studio's schema browser read from it;
drift is detected by diffing a fresh introspection against the snapshot.
Source: packages/spec/src/data/external-catalog.zod.ts
import { ExternalCatalogSchema, ExternalColumnSchema, ExternalTableSchema } from '@objectstack/spec/data' ; import type { ExternalCatalog, ExternalColumn, ExternalTable } from '@objectstack/spec/data' ; // Validate data const result = ExternalCatalogSchema. parse (data); Property Type Required Description name string✅ Catalog id, conventionally <datasource>_catalog. datasource string✅ Datasource.name this catalog snapshots. snapshotAt string✅ When the snapshot was taken (ISO 8601). dialect stringoptional Remote SQL dialect, when known. tables { remoteSchema?: string; remoteName: string; columns: object[]; indexes?: object[]; … }[]✅ Snapshotted remote tables.
Property Type Required Description remoteSchema stringoptional Remote schema/database qualifier remoteName string✅ Remote table/view name columns { name: string; sqlType: string; nullable: boolean; primaryKey: boolean; … }[]✅ Remote columns indexes { name: string; columns: string[]; unique: boolean }[]optional Remote indexes, when introspectable rowCountEstimate numberoptional Approximate row count
Property Type Required Description name string✅ Remote column name sqlType string✅ Raw remote SQL type (e.g. "numeric(10,2)") nullable boolean✅ Whether the remote column is nullable primaryKey booleanoptional (default: false) Part of the remote primary key suggestedFieldType stringoptional ObjectStack field type suggested by the type-compat matrix
Property Type Required Description remoteSchema stringoptional Remote schema/database qualifier remoteName string✅ Remote table/view name columns { name: string; sqlType: string; nullable: boolean; primaryKey: boolean; … }[]✅ Remote columns indexes { name: string; columns: string[]; unique: boolean }[]optional Remote indexes, when introspectable rowCountEstimate numberoptional Approximate row count
Property Type Required Description name string✅ Remote column name sqlType string✅ Raw remote SQL type (e.g. "numeric(10,2)") nullable boolean✅ Whether the remote column is nullable primaryKey booleanoptional (default: false) Part of the remote primary key suggestedFieldType stringoptional ObjectStack field type suggested by the type-compat matrix
ObjectStack