Connector

Connector Protocol - LEVEL 3: Enterprise Connector

Defines the standard connector specification for external system integration. Connectors enable ObjectStack to sync data with SaaS apps, databases, file storage, and message queues through a unified protocol.

Positioning in the sync/integration layering — this file is now the ONLY layer. Both layers above it were retired under ADR-0049 for the same measured reason, that no engine ever executed them: L1 "Simple Sync" (automation/sync.zod.ts) in #4738, and L2 "ETL Pipeline" (automation/etl.zod.ts) in #6414. See packages/spec/docs/SYNC_ARCHITECTURE.md:

Enterprise Connector (THIS FILE) - System integrators - Full SAP integration; connector-attached sync via syncConfig

SCOPE: Most comprehensive integration layer. Includes authentication, webhooks, field mapping, bidirectional sync, retry policies, and complete lifecycle management.

This protocol supports multiple authentication strategies, bidirectional sync, field mapping, webhooks, and comprehensive retry and resilience policies.

What this layer does NOT provide

There is no outbound rate limiting. This header used to advertise "rate limiting" twice — once in the SCOPE line, once as "comprehensive rate limiting" — and no engine ever backed either. connector.rateLimitConfig, and the entire ConnectorRateLimitConfig / RateLimitStrategy shape behind it, was removed in @objectstack/spec 17.0.0 (#4911, ADR-0049 D2), because no outbound rate-limiting engine ever existed. The platform's only token bucket (runtime security/rate-limit.ts) throttles INBOUND requests to us; nothing throttles the calls a connector makes out. Do not substitute shared's RateLimitConfig — that is the inbound limiter and would cap the wrong direction. Until an outbound throttle exists, rate-limit at the connector provider or upstream gateway. What L3 does declare for a rate-limited upstream is retryConfig — whose retryableStatusCodes default [408, 429, 500, 502, 503, 504] includes 429 — and health.circuitBreaker. The full removal reasoning is recorded at the removal site: the "REMOVED: outbound rate limiting" block in integration/connector.zod.ts, and packages/spec/docs/SYNC_ARCHITECTURE.md.

Field mapping does not transform values. This header used to offer "field mapping and transformations"; only the first half was ever true. ConnectorFieldMappingSchema extends the base mapping with exactly three keys — dataType, required and syncMode. FieldMapping.transform was removed in @objectstack/spec 17.0.0 (#5552, ADR-0049), and the whole FieldMappingTransform union went with it (constant / cast / lookup / javascript / map) — no runtime ever executed any of the five. An L3 connector mapping moves a value from source to target; it does not compute one. Value conversion belongs on a surface that runs it: the import mapping's own mapping.fieldMapping[].transform (data/mapping.zod.ts — a string enum, none/constant/map/split/join/lookup, with its settings in params), applied row by row by the REST import path — or an ETL transformation step (L2 above). Already authored the retired key? os migrate meta --from 16 lists the mechanical edits for existing sources — the key itself is removed.

Runtime contract — descriptor vs. registered connector (#2612)

This schema serves TWO distinct consumers; do not conflate them:

Runtime registration (plugin-only). The automation engine's connector registry — what GET /connectors lists and the connector_action flow node dispatches — is populated exclusively by plugins calling engine.registerConnector(def, handlers) with a handler per declared action (ADR-0018 §Addendum). The definition is validated against this schema at registration.
Declarative connectors: stack entries (catalog descriptors). Stack metadata validated against this schema is registered as kind 'connector' for discovery/documentation/marketplace purposes only — it never reaches the runtime registry, because an action here carries no execution binding (deliberately: ADR-0023 rejected re-inventing OpenAPI inside this schema). The automation service warns at boot about declared entries with actions that lack a same-name runtime registration; mark deliberate catalog-only entries with enabled: false. Provider-bound declarative instances that a generic executor (connector-openapi / connector-mcp) materializes at boot are tracked in #2977 (ADR-0097).

Authentication is now imported from the canonical auth/config.zod.ts.

When to Use This Layer

Use Enterprise Connector when:

Building enterprise-grade connectors (e.g., Salesforce, SAP, Oracle)
Complex OAuth2/SAML authentication required
Bidirectional sync with field mapping (dataType / syncMode per field — it moves values, it does not transform them)
Webhook management required
Full CRUD operations and data synchronization
Need comprehensive retry strategies and error handling

Examples:

Full Salesforce integration with webhooks
SAP ERP connector with CDC (Change Data Capture)
Microsoft Dynamics 365 connector

When to downgrade:

Per-field value conversion on import only → the import mapping's own transform (data/mapping.zod.ts), which the REST import path executes row by row. (This used to point at automation/etl.zod.ts; L2 was retired at #6414 for having no executor, so the pointer would have been a signpost landing nowhere — the same defect class this header names below.)

There is no "Trigger Registry" alternative

This header used to carry a "When to use Integration Connector vs. Trigger Registry?" comparison, steering "lightweight" cases to automation/trigger-registry.zod.ts. That file was a third declaration of the connector vocabulary with zero consumers — nothing registered, validated or executed against it — so the guidance pointed authors, with the platform's authority, at a dead end (#4499; removed alongside the #4480 per-provider template cluster). The same defect class as the capabilities.readOnly prescription #4487 corrected: a signpost must land somewhere enforced. Lightweight cases are served HERE — a connector instance with simple auth. (Both automation-side layers were themselves retired as dead ends of the same class: L1 "Simple Sync" in #4738, L2 etl.zod.ts in #6414. This paragraph named L2 as the transformation destination until the second retirement; a signpost that must land somewhere enforced cannot make an exception for itself.)

Source: packages/spec/src/integration/connector.zod.ts

TypeScript Usage

import { CircuitBreakerConfigSchema, ConnectorSchema, ConnectorActionSchema, ConnectorActionEffectSchema, ConnectorConflictResolutionSchema, ConnectorErrorCategorySchema, ConnectorFieldMappingSchema, ConnectorHealthSchema, ConnectorInstanceAPIKeyAuthSchema, ConnectorInstanceAuthSchema, ConnectorInstanceBasicAuthSchema, ConnectorInstanceBearerAuthSchema, ConnectorInstanceNoAuthSchema, ConnectorRetryStrategySchema, ConnectorStatusSchema, ConnectorTriggerSchema, ConnectorTypeSchema, DataSyncConfigSchema, DeclarativeConnectorEntrySchema, ErrorMappingConfigSchema, ErrorMappingRuleSchema, HealthCheckConfigSchema, RetryConfigSchema, SyncStrategySchema, WebhookConfigSchema, WebhookEventSchema, WebhookSignatureAlgorithmSchema } from '@objectstack/spec/integration';
import type { CircuitBreakerConfig, Connector, ConnectorAction, ConnectorActionEffect, ConnectorConflictResolution, ConnectorErrorCategory, ConnectorFieldMapping, ConnectorHealth, ConnectorInstanceAPIKeyAuth, ConnectorInstanceAuth, ConnectorInstanceBasicAuth, ConnectorInstanceBearerAuth, ConnectorInstanceNoAuth, ConnectorRetryStrategy, ConnectorStatus, ConnectorTrigger, ConnectorType, DataSyncConfig, DeclarativeConnectorEntry, ErrorMappingConfig, ErrorMappingRule, HealthCheckConfig, RetryConfig, SyncStrategy, WebhookConfig, WebhookEvent, WebhookSignatureAlgorithm } from '@objectstack/spec/integration';

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

CircuitBreakerConfig

Circuit breaker configuration

Property	Type	Required	Description
enabled	`boolean`	✅	Enable circuit breaker
failureThreshold	`number`	optional (default: `5`)	Failures before opening circuit
resetTimeoutMs	`number`	optional (default: `30000`)	Time in open state before half-open
halfOpenMaxRequests	`number`	optional (default: `1`)	Requests allowed in half-open state
monitoringWindow	`number`	optional (default: `60000`)	Rolling window for failure count in ms
fallbackStrategy	`Enum<'cache' \| 'default_value' \| 'error' \| 'queue'>`	optional	Fallback strategy when circuit is open

Property	Type	Required	Description
name	`string`	✅	Unique connector identifier
label	`string`	✅	Display label
type	`Enum<'saas' \| 'database' \| 'file_storage' \| 'message_queue' \| 'api' \| 'custom'>`	✅	Connector type
description	`string`	optional	Connector description
icon	`string`	optional	Icon identifier
authentication	`{ type: 'oauth2'; authorizationUrl: string; tokenUrl: string; clientId: string; … } \| { type: 'api-key'; key: string; headerName?: string; paramName?: string } \| { type: 'basic'; username: string; password: string } \| { type: 'bearer'; token: string } \| { type: 'none' }`	optional (default: `{"type":"none"}`)	Authentication configuration (runtime shape with inline secrets — plugin-supplied at registerConnector). Authored entries must not inline secrets: use `auth.credentialRef` on a provider-bound instance.
provider	`string`	optional	Generic-executor key that materializes this declarative entry at boot (e.g. openapi/mcp/rest). Omit for a catalog-only descriptor. Unknown provider ⇒ hard boot error (ADR-0097).
providerConfig	`Record<string, any>`	optional	Provider-specific config validated by the provider factory at boot (e.g. `{ spec, baseUrl }` for openapi, where spec is an inline document, a package-relative file path like './billing-openapi.json', or an http(s) URL). Requires `provider`.
auth	`{ type: 'none' } \| { type: 'bearer'; credentialRef: string } \| { type: 'api-key'; credentialRef: string; headerName?: string; paramName?: string } \| { type: 'basic'; username: string; credentialRef: string }`	optional	Declarative instance auth — references credentials via `credentialRef` (resolved at boot), never inline secrets. Requires `provider` (ADR-0097).
actions	`{ key: string; label: string; description?: string; inputSchema?: Record<string, any>; … }[]`	optional
triggers	`{ key: string; label: string; description?: string; type: Enum<'polling' \| 'webhook'>; … }[]`	optional	Trigger definitions
syncConfig	`{ strategy?: Enum<'full' \| 'incremental' \| 'upsert' \| 'append_only'>; direction?: Enum<'import' \| 'export' \| 'bidirectional'>; schedule?: string \| object; realtimeSync?: boolean; … }`	optional	Data sync configuration
fieldMappings	`{ source: string; target: string; defaultValue?: any; dataType?: Enum<'string' \| 'number' \| 'boolean' \| 'date' \| 'datetime' \| 'json' \| 'array'>; … }[]`	optional	Field mapping rules
webhooks	`{ name: string; label?: string; object?: string; triggers?: Enum<'create' \| 'update' \| 'delete' \| 'bulk_update' \| 'bulk_delete'>[]; … }[]`	optional	Webhook configurations
rateLimitConfig	`never`	optional	[REMOVED] `connector.rateLimitConfig` was removed in @objectstack/spec 17.0.0 (ADR-0049 D2) — the entire shape is gone, not just this key: `ConnectorRateLimitConfig` and its `RateLimitStrategy` enum were removed with it, because no outbound rate-limiting engine ever existed. The platform's only token bucket (runtime `security/rate-limit.ts`) throttles INBOUND requests to us; nothing throttled the calls a connector makes out, so every knob here was inert while reading like a configured cap. Delete the key. Do NOT substitute `shared` `RateLimitConfig` — that is the inbound limiter and would cap the wrong direction; until an outbound throttle exists, rate-limit at the connector provider or upstream gateway. Run `os migrate meta --from 16` to list the mechanical edits for existing sources; apply them by hand.
retryConfig	`{ strategy?: Enum<'exponential_backoff' \| 'linear_backoff' \| 'fixed_delay' \| 'no_retry'>; maxAttempts?: number; initialDelayMs?: number; maxDelayMs?: number; … }`	optional	Retry configuration
connectionTimeoutMs	`number`	optional (default: `30000`)	Connection timeout in ms
requestTimeoutMs	`number`	optional (default: `30000`)	Request timeout in ms
status	`Enum<'active' \| 'inactive' \| 'error' \| 'configuring'>`	optional (default: `"inactive"`)	Connector status
enabled	`boolean`	optional (default: `true`)	Enable connector. On declarative stack entries, false marks a deliberate catalog-only descriptor.
errorMapping	`{ rules: object[]; defaultCategory?: Enum<'validation' \| 'authorization' \| 'not_found' \| 'conflict' \| 'rate_limit' \| …>; unmappedBehavior: Enum<'passthrough' \| 'generic_error' \| 'throw'>; logUnmapped?: boolean }`	optional	Error mapping configuration
health	`{ healthCheck?: object; circuitBreaker?: object }`	optional	Health and resilience configuration
metadata	`Record<string, any>`	optional	Custom connector metadata
_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.

Property	Type	Required	Description
type	`'oauth2'`	✅
authorizationUrl	`string`	✅	OAuth2 authorization endpoint
tokenUrl	`string`	✅	OAuth2 token endpoint
clientId	`string`	✅	OAuth2 client ID
clientSecret	`string`	✅	OAuth2 client secret (typically from ENV)
scopes	`string[]`	optional	Requested OAuth2 scopes
redirectUri	`string`	optional	OAuth2 redirect URI
refreshToken	`string`	optional	Refresh token for token renewal
tokenExpiry	`number`	optional	Token expiry timestamp

Property	Type	Required	Description
type	`'api-key'`	✅
key	`string`	✅	API key value
headerName	`string`	optional (default: `"X-API-Key"`)	HTTP header name for API key
paramName	`string`	optional	Query parameter name (alternative to header)

Connector

On this page