Module @contentful/optimization-api-schemas - v1.0.0
Contentful Personalization & Analytics
API Schema Library
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.
Table of Contents
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 {
isResolvedOptimizedEntry,
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 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
ContentType
Other
- NormalizedOptimizationConfig
- OptimizationEntryFields
- OptimizedEntryFields
- AliasEvent
- App
- AudienceEntry
- AudienceEntryFields
- AudienceEntrySkeleton
- BatchExperienceEvent
- BatchExperienceEventArray
- BatchExperienceRequestData
- BatchExperienceResponse
- BatchExperienceResponseData
- BatchInsightsEvent
- BatchInsightsEventArray
- Campaign
- Change
- ChangeArray
- Channel
- ClickEvent
- Dictionary
- EntryReplacementComponent
- EntryReplacementVariant
- ExperienceData
- ExperienceEvent
- ExperienceEventArray
- ExperienceEventType
- ExperienceRequestData
- ExperienceRequestOptions
- ExperienceResponse
- Flags
- GeoLocation
- GroupEvent
- HoverEvent
- IdentifyEvent
- InlineVariableComponent
- InsightsEvent
- InsightsEventArray
- InsightsEventType
- InteractionEventProperties
- Json
- Library
- MergeTagEntry
- MergeTagEntryFields
- MergeTagEntrySkeleton
- OptimizationComponent
- OptimizationComponentArray
- OptimizationConfig
- OptimizationData
- OptimizationEntry
- OptimizationEntryArray
- OptimizationEntrySkeleton
- OptimizationType
- OptimizedEntry
- OptimizedEntrySkeleton
- Page
- PageEventContext
- PageViewEvent
- PartialProfile
- Profile
- Properties
- ResponseEnvelope
- Screen
- ScreenEventContext
- ScreenViewEvent
- SelectedOptimization
- SelectedOptimizationArray
- SessionStatistics
- TrackEvent
- Traits
- UniversalEventContext
- UniversalEventProperties
- UnknownChange
- VariableChange
- ViewEvent
- AliasEvent
- App
- AudienceEntryFields
- BatchExperienceEvent
- BatchExperienceEventArray
- BatchExperienceRequestData
- BatchExperienceResponse
- BatchExperienceResponseData
- BatchInsightsEvent
- BatchInsightsEventArray
- Campaign
- Change
- ChangeArray
- ChangeBase
- ChangeType
- Channel
- ClickEvent
- Dictionary
- EntryReplacementComponent
- EntryReplacementVariant
- ExperienceData
- ExperienceEvent
- ExperienceEventArray
- ExperienceRequestData
- ExperienceRequestOptions
- ExperienceResponse
- GeoLocation
- GroupEvent
- HoverEvent
- IdentifyEvent
- InlineVariableComponent
- InlineVariableComponentValueType
- InlineVariableVariant
- InsightsEvent
- InsightsEventArray
- InteractionEventProperties
- Library
- MergeTagEntryFields
- OptimizationComponent
- OptimizationComponentArray
- OptimizationConfig
- OptimizationEntryFields
- OptimizationType
- OptimizedEntryFields
- Page
- PageEventContext
- PageViewEvent
- PartialProfile
- Profile
- Properties
- ResponseEnvelope
- Screen
- ScreenEventContext
- ScreenViewEvent
- SelectedOptimization
- SelectedOptimizationArray
- SessionStatistics
- TrackEvent
- Traits
- UniversalEventContext
- UniversalEventProperties
- UnknownChange
- VariableChange
- VariableChangeValue
- ViewEvent
- isEntryReplacementComponent
- isEntryReplacementVariant
- isInlineVariableComponent
- isMergeTagEntry
- isRecord
- isResolvedAudienceEntry
- isResolvedContentfulEntry
- isResolvedOptimizationEntry
- isResolvedOptimizedEntry
- isRichTextDocument
- isRichTextNode
- isUnresolvedEntryLink
- normalizeOptimizationConfig
- parseWithFriendlyError
Contentful Optimization API Schema Library.
Remarks
A collection of Zod Mini schemas and their inferred TypeScript types that provide run-time validation for Optimization SDK API requests and responses.