[Content Collections] Allow Zod unions, objects, and transforms as schemas

[bholmesdev]

Changes

• Allow Zod objects, unions, discriminated unions, intersections, and transform results as schemas
• Add helpful warning when z.object(...) wrapper is missing

Why?

By enforcing the z.object(...) wrapper, we open the door for:

• using a transform to add and modify frontmatter properties

const blog = defineCollection({
  schema: z.object({
    youtube: z.string().url(),
  }).transform(data => ({
    embedUrl: toEmbedUrl(data.youtube),
    thumbnailUrl: toThumbnailUrl(data.youtube),
  })
});

• using unions and discriminated unions for supporting multiple schemas on the same collection. This is common when splitting multiple options based on a type property:

const posts = defineCollection({
	schema: z.discriminatedUnion('type', [
		z.object({
			type: z.literal('post'),
			title: z.string(),
			description: z.string(),
		}),
		z.object({
			type: z.literal('newsletter'),
			subject: z.string(),
		}),
	]),
});

Testing

Add a test for Zod unions

Docs

withastro/docs#2335

[changeset-bot]

⚠️ No Changeset found

Latest commit: 8c4ef10

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[matthewp]

Why do we have to require the use of z.object() to get those things?

[natemoo-re]

Definitely in favor of supporting this but I'm not convinced we need to deprecate the current raw object support?

[natemoo-re]

Seems like we could allow POJOs (plain ole' JS objects) here and automatically wrap them with z.object if necessary? Small convenience if you don't need any of the advanced z.object features.

[bholmesdev]

@matthewp @natemoo-re Alright, reasons I'm in favor of deprecating the raw object:

Requiring z.object makes makes shared schemas easier to document. Allowing POJOs today, we encourage this pattern:

const schema1 = {...}
const schema2 = {...}

const blog = defineCollection({
  schema: { ...schema1, ...schema2, moreProperties: true },
});

Now, say schema1 needs a transform. schema1 would need to change from a POJO to an object:

const schema1 = z.object({ ... }).transform(...)
const schema2 = {...}

const blog = defineCollection({
  schema: ???,
});

...and now schema1 and schema2 are difficult to combine. This problem is more pronounced when schemas come from third party libraries.

Requiring schemas to be Zod types, we can always document and encourage a union like so:

const schema1 = z.object({ ... }).transform(...)
const schema2 = z.object({ ... })

const blog = defineCollection({
  schema: z.union([schema1, schema2, z.object({ moreProperties: true })]),
});

I'm also thinking about how much we'd explain if we document transforms or unions. Allowing POJOs, we'd need an "if you're using an object, change to a Zod object first" warning that'd be nice to avoid.

These are fairly minor complaints I know! I just prefer a single standard for doing things to make features discoverable and easy-to-document.

[delucis]

+1 to a single consistent API here. Omitting the z.object() wrapper is a fairly small aesthetic benefit but sounds like it would increase documentation complexity significantly.

[natemoo-re]

I've been convinced! It's a bit boilerplate-y for the simple use case, but I agree that increasing the documentation complexity isn't worth it.