Schema Overview

​

Why it exists

1. Validation at both boundaries — The host re-parses partner exports at the trust boundary using the exact same schema you author against. A definition is validated twice: once when you write it, once when the host accepts it.
2. No structural twins — Without a shared schema, the host and SDK could have diverged over time. There are no twins now — one schema, imported by both.
3. One workspace contract — The SDK used to validate a weaker workspace-target contract than the host. The workspace-target schema now lives here; the host injects its icon-name check via createWorkspaceTargetListSchema({ isValidIcon }).

​

What’s exported

• IntegrationDefinitionSchema — The strict canonical zod schema
• parseIntegrationDefinition(input) — Parse and validate a definition (throws on failure)
• validateIntegrationDefinitions(defs, firstParty?) — Cross-definition collision detection (throws on collision)
• collectDefinitionFindings / collectCollisionFindings — Non-throwing versions that return structured Finding[] (used by ekanos validate)
• IntegrationDefinition<Schemas> and types — TypeScript types for authoring
• Capability-context types — IntegrationContext, StorageSchemas, etc. (canonical home; re-exported by @ekanos/sdk)
• Workspace-target schema — WorkspaceTargetSchema, createWorkspaceTargetListSchema, normalizeWorkspaceTargets, etc.
• Storage data-type allowlists — ACCOUNT_STORAGE_DATA_TYPES, USER_STORAGE_DATA_TYPES, RESERVED_STORAGE_DATA_TYPES
• Deterministic ids — deriveProductId, derivePlanId
• StandardSchemaV1 and WebhookSignatureScheme — types added in 0.4.0. Partner-facing schema generics (storage keys, action input / output, a webhook’s payloadSchema) are constrained by Standard Schema, so a schema from zod 3 or zod 4 satisfies them

​

Dependency-pure

• At authoring time (SDK validation)
• At the host boundary (integration registration)
• In tests, CLI tools, and CI gates

​

For authoring integrations

import { defineIntegration } from '@ekanos/sdk/integration';

export const integration = defineIntegration({
  slug: 'my-integration',
  name: 'My Integration',
  description: 'What this integration does.',
  version: '0.1.0',
  // … components, tools, storage, etc.
});

​

When you do need it

• Building tools that validate definitions (CLI, validation scripts)
• Testing definitions in isolation
• Validating definitions at runtime
• Writing CI gates or custom validators

​

Publishing order

​

What’s next

• Schema Reference — Complete exported types and schemas with documentation
• SDK: Authoring Guide — How to write defineIntegration()