docs: update output schema type description - #11016
Merged
Merged
Conversation
nicoalbanese
added
the
backport
![vercel[bot]](https://avatars.githubusercontent.com/in/8329?s=60&v=4){kind=small}
| type: 'Zod Schema | JSON Schema', | ||
| description: | ||
| 'The schema of the output that the tool produces. Used for validation and type inference.', | ||
| 'The schema of the output that the tool produces. Used for type inference.', |
Contributor
There was a problem hiding this comment.
Suggested change
| 'The schema of the output that the tool produces. Used for type inference.', | |
| 'The schema of the output that the tool produces. Used for validation and type inference.', |
The documentation incorrectly states that outputSchema is used for "type inference" only, but the implementation actually uses it for validation as well.
View Details
Analysis
Documentation incorrectly omits validation function of outputSchema
What fails: The documentation for the outputSchema parameter in tool() at content/docs/07-reference/01-ai-sdk-core/20-tool.mdx (line 122) states it is "Used for type inference" only, but the implementation actively validates tool outputs against this schema.
How to reproduce:
- Look at
packages/ai/src/ui/validate-ui-messages.tslines 413-417 - the code explicitly callsvalidateTypes()withtool.outputSchemawhentoolPart.state === 'output-available' - Run the test "should throw error when tool output validation fails" in
packages/ai/src/ui/validate-ui-messages.test.tsline 1114 - it demonstrates that passing a tool output that violates theoutputSchemathrows anAI_TypeValidationError - Example: passing
output: { result: 123 }when schema expects{ result: z.string() }fails validation
Result: Documentation is incomplete and misleading - developers don't learn that invalid outputs will be rejected by the validation function
Expected: Documentation should state that outputSchema is used for "validation and type inference" to accurately reflect implementation behavior in validate-ui-messages.ts
gr2m
approved these changes
Dec 9, 2025
gr2m
left a comment
gr2m
left a comment
Collaborator
There was a problem hiding this comment.
I trust you over what what agent vercel is saying 😁
ghost
pushed a commit
that referenced
this pull request
Feb 11, 2026
![vercel-ai-sdk[bot]](https://github.githubassets.com/images/gravatars/gravatar-user-420.png){kind=avatar}
ghost
mentioned this pull request
ghost
removed
the
backport
|
✅ Backport PR created: #12454 |
ghost
pushed a commit
that referenced
this pull request
Feb 11, 2026
This is an automated backport of #11016 to the release-v5.0 branch. FYI @nicoalbanese Co-authored-by: Nico Albanese <49612682+nicoalbanese@users.noreply.github.com>
dinwwwh
added a commit
to middleapi/orpc
that referenced
this pull request
Aug 5, 2026
`createToolFactory` disabled both input and output validation on the assumption that the AI SDK re-validates against the tool schemas. That is only true for input: the AI SDK treats `outputSchema` as type metadata and never validates the value `execute` returns against it (confirmed in [vercel/ai#10222](vercel/ai#10222), docs corrected in [vercel/ai#11016](vercel/ai#11016)). Procedures run as tools therefore skipped their `.output()` schemas entirely, including transforms and defaults. ## Fixes - Output validation stays enabled; only input validation remains disabled, since that half is genuinely redundant. - A handler returning invalid output now rejects with an output validation error instead of passing through silently. - Streamed `asyncIteratorObject` outputs validate every yielded event, and a handler returning a non-iterator now errors instead of being yielded once as the final result (the old fallback branch became unreachable and is removed). ## Testing - A new `generateText` test with a mock model proves the AI SDK returns schema-violating `execute` output untouched, so it will start failing if a future `ai` release adds output validation and makes ours redundant. - Remaining tests cover input validation being skipped, invalid output rejection, per-event stream validation, and non-iterator rejection.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #10222