> ## Documentation Index
> Fetch the complete documentation index at: https://sdk.ekanos.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Schema Overview

> The canonical dependency-pure contract for Ekanos integration definitions.

**`@ekanos/integration-schema`** is the single source of truth for integration definition validation. Both `@ekanos/sdk` (authoring) and the Ekanos host (validation) import and use **the same zod schema** — eliminating hand-written structural twins that could drift.

## Why it exists

A security review identified three problems this package solves:

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

This package depends on **zod only**, as a peer (`^3.25.76 || ^4.0.0`). No `@kit/*`, no React, no `server-only`. It can be used:

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

No cycles, no bloat.

## For authoring integrations

**You don't need to import this package directly.** Use `@ekanos/sdk` instead — it re-exports the types and validates your definition with this schema in `defineIntegration()`:

```typescript theme={null}
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.
});
```

Read the [@ekanos/sdk documentation](/sdk/overview) for the authoring guide.

## When you do need it

Import `@ekanos/integration-schema` when:

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

## Publishing order

This package must be published **before** `@ekanos/sdk`, because the SDK declares `@ekanos/integration-schema` as a runtime dependency. A fresh `npm install @ekanos/sdk` resolves the schema from the registry.

## What's next

* **[Schema Reference](/schema/reference)** — Complete exported types and schemas with documentation
* **[SDK: Authoring Guide](/sdk/overview)** — How to write `defineIntegration()`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.