vercel/ai [email protected]

Vercel AI Library 6.0.201: Fixing Array Output Consistency

Vercel has released version 6.0.201 of its AI library, addressing a subtle but important inconsistency in how the framework handles structured data transformations. The patch corrects behavior in array output mode, ensuring that data validation rules, type coercions, and schema transformations are applied uniformly across different output formats.

TL;DR

• Array output validation gap: Previously, array outputs were validated against schemas but returned raw model data instead of transformed values
• Consistency fix: The patch ensures Zod schema transformations, coercions, defaults, and pipes now work consistently whether you're using object or array output modes
• Impact: Developers using structured outputs with validation schemas will see more predictable behavior and fewer surprises when working with array-formatted responses from AI models

Background

The Vercel AI library provides developers with tools to work with large language models through a unified interface. A critical feature is structured output support—the ability to request that AI models return data in specific formats (JSON objects, arrays, etc.) that conform to predefined schemas using tools like Zod for validation.

Schema validation in this context goes beyond simple type checking. Modern validation libraries like Zod support powerful features including:

• Transforms: Functions that modify data after validation
• Coercions: Automatic type conversions (string "123" becomes number 123)
• Defaults: Fallback values when fields are missing
• Pipes: Chaining multiple validation operations together

The issue arose because the library's array output mode had different behavior from object output mode. While object outputs would apply these transformations, array outputs would validate each element but then return the untransformed raw data from the model. This created inconsistent developer experience and made it harder to rely on schema-defined transformations.

How it works

The output mode distinction

The Vercel AI library supports multiple ways to structure model outputs. Object mode returns single structured items matching a schema, while array mode returns collections of items—each individually validated against the same schema. Both modes leverage Zod for validation, but the transformation pipeline differed between them.

When a developer defined a schema with transformations in array mode, they expected those transformations to apply to each array element, just as they would in object mode. Instead, the validation would confirm each element matched the schema structure, but the returned values wouldn't reflect the transformations defined in that schema.

The validation and transformation pipeline

The fix ensures a unified pipeline for both output modes. After the model generates array data, each element is now:

1. Validated against the Zod schema to confirm structure and type correctness
2. Transformed through any defined schema operations (transforms, coercions, defaults, pipes)
3. Returned as the processed value rather than the raw model output

This means if your schema includes a transformation that converts string dates to Date objects, or a coercion that ensures numeric fields are actual numbers rather than strings, these operations now apply consistently. Similarly, default values specified in your schema are now properly applied to array elements that are missing optional fields.

Practical implications

Consider a schema that coerces string representations of numbers. In object mode, if a model returned {"count": "42"}, the coercion would convert it to {"count": 42}. Previously, in array mode with multiple items, each {"count": "42"} would be validated but returned as-is, bypassing the coercion rule.

This patch aligns the behavior. Developers can now write their validation schemas once and trust that the same transformations apply whether they're requesting single objects or arrays of objects.

The change is backward-compatible in the sense that it makes behavior more correct and consistent, though applications that inadvertently relied on receiving raw untransformed data from array outputs may observe different behavior.

What happens next

Developers using Vercel's AI library should test their array output implementations, particularly those with complex schemas featuring transformations, coercions, or pipes. If your application was working around this inconsistency, you may be able to simplify your code now that schema transformations apply uniformly.

For teams implementing new structured output features, this patch reinforces that schema definitions are now a reliable source of truth for data transformation logic, regardless of whether you're using object or array output modes. This article does not contain affiliate links.