Contentful Personalization & Analytics

API Schema Library

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.

Table of Contents

• 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
Copy

Import schemas or helpers from the package:

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

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 Optimization-owned Contentful fields:

Export	Purpose
OptimizedEntry	Contentful SDK entry type with associated optimization entries
OptimizationEntry	Contentful SDK entry type referenced by fields.nt_experiences
OptimizationConfig	Optimization configuration schema from fields.nt_config
isRecord	Structural guard for non-array object records
isRichTextDocument	Structural guard for Contentful Rich Text documents
isRichTextNode	Structural guard for Contentful Rich Text nodes
isResolvedContentfulEntry	Structural guard for resolved Contentful Entry values
isResolvedOptimizedEntry	Structural guard for resolved optimized entries
isResolvedOptimizationEntry	Structural guard for resolved optimization entries
normalizeOptimizationConfig	Fills omitted optimization config fields with SDK-safe defaults

These schemas model the SDK's single-locale CDA entry contract. Manual resolution passes entries fetched with one app Contentful locale. JS SDK-managed fetching uses the same contract when a contentful.js client is configured. Avoid withAllLocales or locale=* in either 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