Skip to content

Conversation

@dickermoshe
Copy link

@dickermoshe dickermoshe commented Nov 5, 2025

Summary

This PR adds an optional name parameter to the v.object() validator constructor to enable better type generation for Convex clients in languages other than TypeScript.

Problem

When generating type-safe clients for languages without TypeScript's powerful type system (like Python, Java, Go, etc.), we need consistent, reusable type names for object schemas. Currently, without named objects, client generators must create arbitrary names like Object123 or AnonymousObject, making types non-reusable and harder to work with. These types are also not the same across different requests. So 2 functions which return the identical object, return different classes.

Solution

Add an optional name parameter to v.object() that allows developers to specify meaningful names for their object types:

// Before
const userSchema = v.object({
  name: v.string(),
  age: v.number(),
});

// After
const userSchema = v.object({
  name: v.string(),
  age: v.number(),
}, { name: "User" });

This would allow client library authors to generate data models like:

class User(BaseModel):
  name: str
  age: float

which could be used across multiple different requests.

The alternative would be:

class ConvexModel835989(BaseModel):
  name: str
  age: float

While TypeScript already handles types internally, providing explicit names could also benefit code generation and type declarations for TypeScript itself. The primary motivation, however, is to support non-TypeScript languages.

Backward Compatibility

This change is fully backward compatible:

  • Existing code using v.object(fields) continues to work unchanged
  • The name parameter is optional and defaults to undefined
  • No breaking changes to the API surface

@dickermoshe dickermoshe changed the title Add name to object validator Add optional name parameter to v.object() for cross-language type safety Nov 5, 2025
@dickermoshe
Copy link
Author

There should probably be a bigger discussion before this gets merged.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant