[Content collections] Documentation should maybe specify that the z.object wrapper is needed?

[Acccent]

📚 Subject area/topic

Content Collections guide – specifically, defining schemas.

📋 Page(s) affected (or suggested, for new content)

https://docs.astro.build/en/guides/content-collections/#defining-a-collection-schema

📋 Explain your issue

Following this change, collection schemas require a z.object wrapper; the examples in the docs have already been changed accordingly.

Personally when reading the docs, it wasn't clear that the examples were demonstrating the required structure – I thought z.object was used as, well, an example.

I would suggest something like this in the documentation for defining schemas (changes in italics):

To define your first collection, create a src/content/config.ts file if one does not already exist (.js and .mjs extensions are also supported.) This file should:

1. Import the proper utilities from astro:content.
2. Define each collection that you'd like to validate. Collections must include:
   - A type (introduced in Astro v2.5.0) specifying whether the collection contains content authoring formats like Markdown (type: 'content') or data formats like JSON or YAML (type: 'data');
   - A schema that defines the shape of your frontmatter or entry data, using a Zod object as a base (z.object({...})).
3. Export a single collections object to register your collections.

[Acccent]

Note that I suppose the schema actually does accept a few other things besides z.object (withastro/astro#8163), but I don't know how to explain this in a way that wouldn't just add confusion. I guess anyone using the more advanced types that are valid would know that they will be accepted.

[TheOtterlord]

Thanks for the feedback!

We clarify usage of Zod in a later section (Defining datatypes with Zod). We could maybe append "using Zod" to clarify what we're using to define a schema?

Define each collection that you’d like to validate. This includes a type (introduced in Astro v2.5.0) specifying whether the collection contains content authoring formats like Markdown (type: 'content') or data formats like JSON or YAML (type: 'data'). It also includes a schema that defines the shape of your frontmatter or entry data, using Zod.

[Acccent]

I think (again this is just me) the problem isn't so much about clarifying the use of Zod (which is fairly well documented), but the use of Zod objects. I set up several schemas using z.array() or even z.string() for data collections and I couldn't figure out for the longest time where all the issues were coming from, because I was using Zod in a presumably correct way and it was all getting compiled normally.

Basically I wish I had known beforehand that this isn't setup correctly, and why:

const col = defineCollection({
  type: 'data',
  schema: z.array(
      z.object({
        title: z.string(),
        desc: z.string(),
      })
    ),
});

[delucis]

I'd expect arrays to be valid in data collections, so if they're not, it might be a bug.

[Acccent]

Honestly same, and if arrays could be supported in data collections that would indeed make my life a lot easier! but since you specified in issue 8163 (linked above) that they aren't, I figured there must be some reason 😝

[TheOtterlord]

@Acccent I've created an example on the latest version, which seems to work fine: Stackblitz

We could probably use an example somewhere on the page, to make it clear this is a supported use-case.

[delucis]

since you specified in issue 8163 (linked above) that they aren't, I figured there must be some reason 😝

Yeah in withastro/astro#8163 I was specifically solving a content collection schema issue and had not considered data collections. We should probably make the supported types for content and data collections different to support a wider range in data collections.

[Acccent]

Okay, it looks like it was fixed in the last few releases :) Sorry about the false alarm and thanks for checking it!