vercel/ai [email protected]

Vercel AI SDK 5.0.199: Fixing Inconsistent Data Transformation in Array Mode

Vercel has released a patch update to its popular AI SDK that addresses a subtle but important bug in how the framework handles data validation when processing arrays of structured outputs from language models. The fix ensures that schema transformations are applied consistently whether you're working with single objects or multiple array elements—a detail that matters significantly for production applications relying on predictable data handling.

TL;DR

• Schema transformations: Zod validators can apply transformations, type coercions, default values, and data pipelines to raw model outputs
• Array output inconsistency: The previous version validated array elements against schemas but returned untransformed raw data, unlike object mode which applied transformations
• Consistent behavior: The patch ensures transformed values are returned in array mode, matching the behavior of object output
• Impact: Developers can now rely on uniform data handling across different output modes, eliminating edge cases where business logic depends on schema-defined transformations

Background

The Vercel AI SDK provides developers with a unified interface for working with language models from various providers (OpenAI, Anthropic, Google, etc.). A critical feature of this SDK is its integration with Zod, a popular TypeScript schema validation library. This integration allows developers to define structured schemas for AI outputs—essentially telling the model "I want you to return data matching this specific shape."

Zod's power extends beyond simple validation. Developers can define transformations that automatically modify data during validation—converting strings to numbers, applying default values, normalizing fields, or running custom processing pipelines. This has become a standard pattern in TypeScript applications for ensuring data integrity and consistency.

The SDK supports different output modes for handling multiple results from models: you can request a single object or an array of objects. Previously, these modes handled schema transformations differently, creating an inconsistency that could lead to unexpected behavior in production applications.

How it works

Understanding Output Modes and Validation

The AI SDK allows you to specify how you want structured data returned from language models. When using object output mode, you define a Zod schema, and the model returns a single validated object. When using array output mode, the model returns multiple objects matching that schema.

The critical difference exposed by this bug was in what happened after validation. In object mode, if your schema defined a transformation—say, converting a string field to a number or applying a computed default—that transformation would be applied to the final result. In array mode, the validation would pass (confirming the data matched the schema), but the raw, untransformed data would be returned instead.

The Practical Problem

Consider a real-world example: a developer creates a Zod schema for extracting product information from images. The schema includes a price field defined as a string that should be coerced to a number via transformation. When requesting a single product (object mode), the returned price would be a proper number. But when requesting multiple products in an array, the prices would come back as strings despite the schema defining they should be numbers. The developer's downstream code expecting numbers would then fail or behave unexpectedly.

This inconsistency violated the principle of least surprise—developers reasonably expected that defining a transformation in a schema meant that transformation would happen regardless of whether they requested one result or many.

The Fix

The patch modifies the array output validation logic to return schema-transformed elements rather than raw model output. This brings array mode into alignment with object mode behavior. Now when a schema defines transformations, defaults, type coercions, or pipes (Zod's term for chained operations), all of these are consistently applied in both modes.

Under the hood, this likely involved changing the validation step from a simple "does this pass validation?" check to actually using Zod's .parse() method (which returns transformed data) instead of .safeParse() with manual result handling (which might only validate without fully applying transformations).

What happens next

If you're using the Vercel AI SDK with structured outputs and array mode, updating to 5.0.199 ensures your data transformations work reliably. This is particularly important if you've built business logic that depends on schema-defined transformations, or if you're considering using such transformations in arrays.

For developers not yet leveraging schema transformations, this change has no operational impact, but it's good to know the behavior is now consistent should you decide to use Zod's more advanced features in the future.

This type of fix—addressing subtle behavioral inconsistencies—represents the kind of refinement that makes frameworks more reliable and predictable as they mature. If you're building AI-powered applications with structured outputs, maintaining a current version of the SDK ensures you're working with consistent, predictable behavior across all your output modes. This article does not contain affiliate links.