Explain how the reference() helper function transforms the data

[MoritzLost]

📚 Subject area/topic

Content Collections

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

https://docs.astro.build/en/guides/content-collections/#defining-collection-references
https://docs.astro.build/en/guides/content-collections/#accessing-referenced-data

📋 Description of content that is out-of-date or incorrect

The documentation for the reference() utility function is lacking some info. From the description, I only assumed it adds type-safety to referenced items (possibly validating that an item with that ID exists, still not sure if it actually does that or if that's even technically possible). However, it also transforms the property.

For example, if I define a property using the reference helper:

schema: z.object({
    crop: reference('crops'),
}),

And then specify an ID in a collection item:

{
    "crop": "grapevine"
}

Now if I access that property, it's not a string any more, but an object containing both the collection and id:

myItem.data.crop; // { collection: 'crops', id: 'grapevine' }

This is what allows me to use getEntry without specifying a collection:

const crop = await getEntry(myItem.data.crop);

I was surprised by this and actually thought there was a bug (withastro/astro#13052), because I didn't asume the reference() utility would transform the value of the property.

Suggested improvements

• The documentation on defining collection references should mention that the reference() function transforms the property to an object, and how to work with that in a template
• The documentation on accessing referenced data should explain that it's possible to use getEntry without specifying a collection because of the above-mentioned transforms. Right now, this is easy to miss in the code example.

🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)

No response

[sarah11918]

Thanks for this comment! I agree this looks like something we should be saying, and show an example in docs!

I'm adding help wanted and would welcome a PR (also check the linked issue for more context!) to add this!