Guides · Reference · Contributing

[!WARNING]

The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time.

The Contentful Optimization API Schema Library provides Zod Mini schemas, inferred TypeScript types, and small runtime helpers for Contentful CDA, Experience API, and Insights API payloads. SDK layers use this package to validate API contracts and normalize optimization data.

• Getting started
• When to use this package
• Package surface
  • Contentful CDA helpers
  • Experience API schemas
  • Insights API schemas
• Related

Getting started

Install using an NPM-compatible package manager, pnpm for example:

pnpm install @contentful/optimization-api-schemas

Import schemas or helpers from the package:

import { isOptimizedEntry, normalizeOptimizationConfig } from '@contentful/optimization-api-schemas'

Consult Zod's documentation for more information on working with Zod Mini schemas.

When to use this package

Use @contentful/optimization-api-schemas when you need shared runtime validation schemas or inferred TypeScript types for Contentful CDA, Experience API, and Insights API payloads. Most application integrations must use an environment SDK instead of importing schemas directly.

Package surface

Contentful CDA helpers

These helpers identify and normalize Contentful entries for optimization:

| Export | Purpose | | ----------------------------- | --------------------------------------------------------------- | | CtflEntry | Generic Contentful entry schema | | OptimizedEntry | Entry schema with associated optimization entries | | OptimizationEntry | Optimization entry schema referenced by fields.nt_experiences | | OptimizationConfig | Optimization configuration schema from fields.nt_config | | isEntry | Type guard for Contentful Entry values | | isOptimizedEntry | Type guard for optimized entries | | isOptimizationEntry | Type guard for optimization entries | | normalizeOptimizationConfig | Fills omitted optimization config fields with SDK-safe defaults |

These schemas model the SDK's single-locale CDA entry contract. Fetch entries in the app layer with one CDA locale. Use the resolved SDK locale, withOptimizationLocale(contentfulClient), or the Node SDK's resolveRequestLocale() result before passing entries to SDK resolution helpers. Avoid withAllLocales or locale=* in that path. See Entry personalization and variant resolution for the entry contract and Locale handling in the Optimization SDK Suite for the broader locale model.

Experience API schemas

Experience API schemas validate profile evaluation request and response payloads:

| Export | Purpose | | ---------------------------- | -------------------------------------------------------- | | ExperienceRequestData | Request payload for a single Experience API call | | BatchExperienceRequestData | Request payload for batch Experience API calls | | ExperienceEvent | Union of supported Experience API event schemas | | BatchExperienceEvent | Batch event schema with required anonymousId per event | | ExperienceResponse | Full Experience API response envelope | | BatchExperienceResponse | Batch Experience API response envelope | | Change | Supported change union, including Custom Flag data | | SelectedOptimization | Selected optimization outcome for a profile | | Profile | User profile returned by the Experience API |

Insights API schemas

Insights API schemas validate event ingestion payloads:

| Export | Purpose | | -------------------- | ----------------------------------------------------------- | | InsightsEvent | Union of supported Insights API event schemas | | BatchInsightsEvent | Batched Insights API payload with profile and event entries | | ClickEvent | component_click event schema | | HoverEvent | component_hover event schema | | ViewEvent | component view event schema |

For every schema, inferred type, and helper signature, use the generated API Schemas reference.

Related

• API Schemas generated reference - exported schema and type reference
• API Client - low-level Experience API and Insights API transport
• Optimization Core SDK - platform-agnostic SDK layer that consumes these schemas
• Choosing the right SDK - package selection guidance for application integrations