docs: clarify schema behavior for collection entry data #9964
Conversation
✅ Deploy Preview for astro-docs-2 ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify site configuration. |
apatel369
changed the title
| @@ -249,6 +249,7 @@ const dogs = defineCollection({ | |||
|
|
|||
| export const collections = { blog, dogs }; | |||
| ``` | |||
| If the property is not defined in the Zod schema, it will be excluded from the collection entry data. | |||
There was a problem hiding this comment.
Maybe it could be better highlighted as a note or a caution, eg.
There was a problem hiding this comment.
Nice suggestion. Initially I got the same idea. I just kept it just normal text because I am not fully aware about writing style of astro docs when to use note or caustion or normal text. I will wait for maintainers feeback on this.
There was a problem hiding this comment.
Thanks @apatel369 !
Also, I've been recently thinking, in terms of functionality, if it is not rather about including than excluding when speaking of schema related data, would make sense, eg.
, if it is functionally correct that schema potentially filters out undeclared properties.
There was a problem hiding this comment.
Great discussion here folks! 🙌
I will point out that yes, @apatel369 is familiar with our docs style and we rarely add cautions, notes etc. in favour of putting the information in its proper place! Otherwise, the page can become a patchwork of big colour blobs every time someone wants to update documentation. 😄
So, instead, I've looked up where we do mention schema frontmatter properties, and where any extra content would go, and line 226 says:
Every frontmatter or data property of your collection entries must be defined using a Zod data type
So, you can see how your proposed sentences now feel a little odd with that existing text. (This is the other benefit of not just slapping a note down! Otherwise, you might have added something at odds with existing text!)
Given all that (that no, you cannot add a note; and no, the bottom of a code sample far removed from where we explain using Zod for frontmatter properties is not the place for it), what would be your suggestion for improving the existing line of text to address the concern you have?
There was a problem hiding this comment.
Thanks Sarah, that's a good point. The mentioned line tbh actually beats me, because I have questions about the functionality itself, and also it might be a tough nut for my english the way I see it atm.
The only thing I can tell about that sentence is that it tells me I have to use zod syntax to define schemas, but not about the "including only" or "excluding" behavior on actual data based on the defined schema, which I don't know if it's a self given functionality of schemas in general, an astro feature or a potential bug.
There was a problem hiding this comment.
@jurajkapsz Sorry for the confusion. I hear you and appreciate your feedback. I've also read your comment on the original issue. I will investigate this further and get back to you soon with more information.
There was a problem hiding this comment.
The only thing I can tell about that sentence is that it tells me I have to use zod syntax to define schemas,
Yes, this has been our recommendation as this is what guarantees the typesafety. I guess what you've both discovered here is that it's possible to have a property not defined by Zod, but then it technically does not become part of your collection data.
I'm wondering how documenting this is a benefit? Is there a helpful use case for knowing that untyped data can "exist but not be used"? Sometimes in docs we don't mention everything that is possible, but describe the "happy path" simple case for everyone. It seemed to me like the original note was intended to be a kind of warning that you need to define every property, or it won't be part of your collection. If the goal is to tell/remind people to make Zod definitions, then saying "Every property in your collection must have a Zod definition" is a pretty clear instruction to do that on its own, I think? If you read that, you're left concluding that you need to make a Zod definition and... that's what we want! 😄 In which case, I'm not sure any change to existing documentation is needed?
If the intention is to say, "Don't worry if you can't define everything! You can still have extra data that's not defined, it just won't be a part of your collection. This is useful when..." Then THAT is a different story, but I'd need to know how that is a popular/helpful use case. It seems that this is not the intended use of content collections, and we typically don't document "possible but unsupported/unrecommended use." But if this use is helpful to people who otherwise couldn't have collections, then I get saying something.
So I guess it all comes down to the original intention of this PR?
There was a problem hiding this comment.
Thanks @apatel369 , @sarah11918 ! I was writing back, but I think I've found what it's all about, citing:
By default, Zod object schemas strip out unrecognized keys during parsing. This means that if a user provides data with extra or unknown properties, Zod will remove them, conforming to the defined schema.
See also .passthrough.
So this is by the looks the behavior I ran into. I don't think it is particularly mentioned in [astro] docs (at least not content collections), but it's probably a common knowledge about Zod I wasn't aware of - haven't used Zod as a lib before.
I am not sure if this can or should be part of Astro docs, nor some runtime logs.
I'd like to appreciate very much for your help Arpan and Sarah!
There was a problem hiding this comment.
@jurajkapsz Glad that you found it. Since it is a Zod thing, I don't think we need to add it in Astro docs.
There was a problem hiding this comment.
Just noting that I left a comment in the original Astro issue, as I suspect this is in fact better supported by an error message (if that's technically possible!) rather than a change to docs.
My full comment is here! withastro/astro#12404 (comment)
|
OK so I think the call here is that this is not something for docs, as I'm pretty comfortable with what our docs currently say! Thank you both for this discussion! So I'll close this, but I'll leave the issue open a little longer in case anything comes of that! |
|
Thanks very much Sarah! |
Description (required)
This PR updates the documentation to clarify that any frontmatter or data property of collection entries must be defined using a Zod data type. If a property is not defined using Zod, it will be excluded from the collection entry data. This change aims to improve user understanding of the schema behavior and ensure data validation and consistency.
Related issues & labels (optional)
-Potentially Closes Astro issue #12404
-Suggested label: docs