Contentful Personalization & Analytics

API Schema Library

The Contentful Optimization API Schema Library is a collection of Zod Mini schemas and their inferred TypeScript types. These schemas help provide run-time validation when working with requests and responses for the APIs referenced within Optimization SDKs.

Getting Started

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

pnpm install @contentful/optimization-api-schemas
Copy

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

Contentful CDA Schemas

These schemas assist in determining whether Contentful content entries provided by the CDA and its SDK are valid for personalization. These schemas do not encapsulate all features and functionality specified in the CDA SDK's exported TypeScript type system, but strive to remain compatible enough for the purposes of personalization.

Essential Schemas

• CtflEntry: Zod schema describing a generic Contentful entry; the fields member is loosely typed as any valid JSON
• PersonalizedEntry: Zod schema describing a CtflEntry that has associated personalization entries
• PersonalizationEntry: Zod schema describing a personalization entry, which is associated with a PersonalizedEntry via its fields.nt_experiences property
• PersonalizationConfig: Zod schema describing the configuration of a PersonalizationEntry via its fields.nt_config property

Essential Functions

• isEntry<S extends SkeletonType, M extends ChainModifiers, L extends string>: Type guard that checks whether the given value is a Contentful Entry, passing through the specified skeleton, chain modifiers, and locale
• isPersonalizedEntry: Type guard for PersonalizedEntry
• isPersonalizationEntry: Type guard for PersonalizationEntry

Experience API Schemas

These schemas help validate at run-time that both the request and response data for Experience API requests conform to current API specifications.

Essential Experience API Request Schemas

• ExperienceRequestData: Zod schema describing the data payload for an experience request
• ExperienceEvent: Zod schema union of supported experience/personalization events
• BatchExperienceEvent: Zod schema describing each valid experience/personalization event within a batch; Similar to ExperienceEvent, but with an additional anonymousId member on each event schema

Experience/personalization event schemas:

• AliasEvent: Zod schema describing an alias event
• ComponentViewEvent: Zod schema describing a component view event (may be a Contentful entry or a Custom Flag)
• IdentifyEvent: Zod schema describing an identify event
• PageViewEvent: Zod schema describing a page view event
• ScreenViewEvent: Zod schema describing a screen view event
• TrackEvent: Zod schema describing a custom track event

Essential Experience API Response Schemas

• ExperienceResponse: Zod schema describing a full Experience API response; includes a data object with changes, experiences, and profile properties
• BatchExperienceResponse: Zod schema describing a batch experience response from the Experience API; includes a profiles collection
• Change: Union of supported change types, which currently only includes VariableChange; this change type is used for Custom Flags
• SelectedPersonalization: Zod schema describing a selected personalization outcome for a user
• Profile: Zod schema describing a full user profile as received from the Experience API

Insights API Schemas

Insights API endpoints currently do not return response data.

Essential Insights API Response Schemas

• InsightsEvent: Zod schema union of supported insights/analytics events
• BatchInsightsEvent: Zod schema describing a batched Insights event payload; expects a profile property alongside a collection of events

Insights/analytics event schemas:

• ComponentViewEvent: Zod schema describing a component view event (may be a Contentful entry or a Custom Flag)