ObjectStackExternal 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
TypeScript Usage
import { ExternalCatalog, ExternalColumn, ExternalTable } from '@objectstack/spec/data';
import type { ExternalCatalog, ExternalColumn, ExternalTable } from '@objectstack/spec/data';
// Validate data
const result = ExternalCatalog.parse(data);ExternalCatalog
Properties
| 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 | string | optional | Remote SQL dialect, when known. |
| tables | Object[] | ✅ | Snapshotted remote tables. |
ExternalColumn
Properties
| 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 | boolean | ✅ | Part of the remote primary key |
| suggestedFieldType | string | optional | ObjectStack field type suggested by the type-compat matrix |
ExternalTable
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| remoteSchema | string | optional | Remote schema/database qualifier |
| remoteName | string | ✅ | Remote table/view name |
| columns | Object[] | ✅ | Remote columns |
| indexes | Object[] | optional | Remote indexes, when introspectable |
| rowCountEstimate | number | optional | Approximate row count |