Data collections and collection references

src/content/docs/en/guides/content-collections.mdx

@@ -20,9 +20,9 @@ import TypeScriptSettingTabs from '~/components/tabs/TypeScriptSettingTabs.astro
 
 ## What are Content Collections?
 
-A **content collection** is any directory inside the reserved `src/content` project directory, such as `src/content/newsletter` and `src/content/blog`. Only content collections are allowed inside the `src/content` directory. This directory cannot be used for anything else.
+A **content collection** is any directory inside the reserved `src/content` project directory, such as `src/content/newsletter` and `src/content/authors`. Only content collections are allowed inside the `src/content` directory. This directory cannot be used for anything else.
 
-A **content entry** is any piece of content stored inside of your content collection directory. Content entries are stored as either Markdown (`.md`) or MDX (`.mdx`) files. You can use any filename you want, but we recommend using a consistent naming scheme (lower-case, dashes instead of spaces) to make it easier to find and organize your content.
+A **collection entry** is any piece of content stored inside of your content collection directory. Entries can use content authoring formats including Markdown (`.md`) and MDX (`.mdx`) or as data formats including YAML (`.yaml`) and JSON (`.json`). You can use any filename you want, but we recommend using a consistent naming scheme (lower-case, dashes instead of spaces) to make it easier to find and organize your content.
 
 <FileTree>
 - src/content/
@@ -52,7 +52,7 @@ echo "\n.astro" >> .gitignore
 
 ### Organizing with multiple collections 
 
-If two files represent different kinds of content (e.g. a blog post and an author profile), they most likely belong in different collections. This is important because many features (frontmatter validation, automatic TypeScript type-safety) require that all entries in a collection share a similar frontmatter structure.
+If two files represent different kinds of content (e.g. a blog post and an author profile), they most likely belong in different collections. This is important because many features (frontmatter validation, automatic TypeScript type-safety) require that all entries in a collection share a similar structure.
 
 If you find yourself working with different types of content, you should create multiple collections to represent each type. You can create as many different collections in your project as you'd like.
 
@@ -61,11 +61,12 @@ If you find yourself working with different types of content, you should create
   - **newsletter/** 
     - week-1.md
     - week-2.md
-    - week-3.md
-  - **authors/** split different content types into new collections
-    - grace-hopper.md
-    - alan-turing.md
-    - batman.md
+  - **blog/**
+    - post-1.md
+    - post-2.md
+  - **authors/**
+    - grace-hopper.json
+    - alan-turing.json
 </FileTree>
 
 
@@ -134,28 +135,31 @@ If you use `.js` or `.mjs` files in an Astro project, you can enable IntelliSens
 
 ### Defining a collection schema
 
-Schemas enforce consistent frontmatter within a collection. A schema **guarantees** that your frontmatter exists in a predictable form when you need to reference or query it. If any file violates its collection schema, Astro will provide a helpful error to let you know.
+Schemas enforce consistent frontmatter or entry data within a collection. A schema **guarantees** that this data exists in a predictable form when you need to reference or query it. If any file violates its collection schema, Astro will provide a helpful error to let you know.
 
 Schemas also power Astro's automatic TypeScript typings for your content. When you define a schema for your collection, Astro will automatically generate and apply a TypeScript interface to it. The result is full TypeScript support when you query your collection, including property autocompletion and type-checking. 
 
-To create your first content schema, create a `src/content/config.ts` file if one does not already exist (`.js` and `.mjs` extensions are also supported). This file should:
+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 with a schema.
-3. Export a single `collections` object to register your collections.
+1. **Import the proper utilities** from `astro:content`. 
+2. **Define each collection that you'd like to validate.** This includes a `type` 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.
+3. **Export a single `collections` object** to register your collections.
 
 ```ts
 // src/content/config.ts
 // 1. Import utilities from `astro:content`
 import { z, defineCollection } from 'astro:content';
-// 2. Define a schema for each collection you'd like to validate.
+
+// 2. Define a `type` and `schema` for each collection
 const blogCollection = defineCollection({
+  type: 'content',
   schema: z.object({
     title: z.string(),
     tags: z.array(z.string()),
     image: z.string().optional(),
   }),
 });
+
 // 3. Export a single `collections` object to register your collection(s)
 export const collections = {
   'blog': blogCollection,
@@ -169,9 +173,18 @@ You can use `defineCollection()` as many times as you want to create multiple sc
 ```ts
 // src/content/config.ts
 export const collections = {
-  'blog': defineCollection({ /* ... */ }),
-  'newsletter': defineCollection({ /* ... */ }),
-  'profile-authors': defineCollection({ /* ... */ }),
+  'blog': defineCollection({
+    type: 'content',
+    schema: z.object({ /* ... */ })
+  }),
+  'newsletter': defineCollection({
+    type: 'content',
+    schema: z.object({ /* ... */ })
+  }),
+  'authors': defineCollection({
+    type: 'data',
+    schema: z.object({ /* ... */ })
+  }),
 };
 ```
 
@@ -181,14 +194,22 @@ As your project grows, you are also free to reorganize your codebase and move lo
 // src/content/config.ts
 // 1. Import your utilities and schemas
 import { defineCollection } from 'astro:content';
-import {blogSchema, newsletterSchema} from '../schemas';
+import {blogSchema, authorSchema} from '../schemas';
+
 // 2. Define your collections
-const blogCollection = defineCollection({ schema: blogSchema });
-const newsletterCollection = defineCollection({ schema: newsletterSchema });
+const blogCollection = defineCollection({
+  type: 'content',
+  schema: blogSchema,
+});
+const authorCollection = defineCollection({
+  type: 'data',
+  schema: authorSchema,
+});
+
 // 3. Export multiple collections to register them
 export const collections = {
   'blog': blogCollection,
-  'newsletter': newsletterCollection,
+  'authors': authorCollection,
 };
 ```
 
@@ -200,7 +221,8 @@ You can import collection schemas from anywhere, including external npm packages
 ```ts
 // src/content/config.ts
 import {blogSchema} from 'my-blog-theme';
-const blogCollection = defineCollection({ schema: blogSchema });
+const blogCollection = defineCollection({ type: 'content', schema: blogSchema });
+
 // Export the blog collection, using an external schema from 'my-blog-theme'
 export const collections = {
   'blog': blogCollection,
@@ -245,9 +267,52 @@ defineCollection({
 })
 ```
 
+### Defining collection references
+
+Collection entries can also "reference" other related entries. A common example is a blog post that references reusable author profiles stored as JSON, or related post URLs stored in the same collection.
+
+You can define these relationships using the `reference()` utility from your collection schema. This accepts a collection name and validates the entry identifier(s) in your frontmatter or data file.
+
+```ts
+import { defineCollection, reference, z } from 'astro:content';
+
+const blog = defineCollection({
+  type: 'content',
+  schema: z.object({
+    title: z.string(),
+    // Reference a single author from the `authors` collection by `id`
+    author: reference('authors'),
+    // Reference an array of related posts from the `blog` collection by `slug`
+    relatedPosts: z.array(reference('blog')),
+  })
+});
+
+const authors = defineCollection({
+  type: 'data',
+  schema: z.object({
+    name: z.string(),
+    portfolio: z.string().url(),
+  })
+});
+
+export const collections = { blog, authors };
+```
+
+This example blog post specifies the `slug`s of related posts and the `id` of the post author:
+
+```yaml title="src/content/blog/welcome.md"
+---
+title: "Welcome to my blog"
+author: ben-holmes # references `src/content/authors/ben-holmes.json`
+relatedPosts:
+- about-me # references `src/content/blog/about-me.md`
+- my-year-in-review # references `src/content/blog/my-year-in-review.md`
+---
+```
+
 ### Defining custom slugs
 
-Every content entry generates a URL-friendly `slug` property from its [file `id`](/en/reference/api-reference/#id). The slug is used to query the entry directly from your collection. It is also useful when creating new pages and URLs from your content.
+When using `type: 'content'`, every content entry generates a URL-friendly `slug` property from its [file `id`](/en/reference/api-reference/#id). The slug is used to query the entry directly from your collection. It is also useful when creating new pages and URLs from your content.
 
 You can override an entry's generated slug by adding your own `slug` property to the file frontmatter. This is similar to the "permalink" feature of other web frameworks. `"slug"` is a special, reserved property name that is not allowed in your custom collection `schema` and will not appear in your entry's `data` property. 
 
@@ -261,26 +326,64 @@ Your blog post content here.
 
 ## Querying Collections
 
-Astro provides two functions to query a collection and return one (or more) content entries: [`getCollection()`](/en/reference/api-reference/#getcollection) and [`getEntryBySlug()`](/en/reference/api-reference/#getentrybyslug).
+Astro provides two functions to query a collection and return one (or more) content entries: [`getCollection()`](/en/reference/api-reference/#getcollection) and [`getEntry()`](/en/reference/api-reference/#getentry).
 
 ```js
-import { getCollection, getEntryBySlug } from 'astro:content';
-// Get all entries from a collection. Requires the name of the collection as an argument.
+import { getCollection, getEntry } from 'astro:content';
+
+// Get all entries from a collection.
+// Requires the name of the collection as an argument.
+// Example: retrieve `src/content/blog/**`
 const allBlogPosts = await getCollection('blog');
-// Get a single entry from a collection. Requires the name of the collection and the entry's slug as arguments.
-const oneBlogPost = await getEntryBySlug('blog', 'enterprise');
+
+// Get a single entry from a collection.
+// Requires the name of the collection and either
+// the entry `slug` (content collections) or `id` (data collections)
+// Example: retrieve `src/content/authors/grace-hopper.json`
+const graceHopperProfile = await getEntry('authors', 'grace-hopper');
 ```
 
 Both functions return content entries as defined by the [`CollectionEntry`](/en/reference/api-reference/#collection-entry-type) type.
 
-#### Filtering collection queries
+### Resolving references
+
+When using [collection references](#defining-collection-references), you can use the `getEntry()` and `getEntries()` functions to retrieve the referenced entry `data`. 
+
+```astro title="src/pages/blog/welcome.astro"
+---
+import { getEntry, getEntries } from 'astro:content';
+
+const { data } = await getEntry('blog', 'welcome');
+
+// Resolve a singular reference
+const author = await getEntry(data.author);
+// Resolve an array of references
+const relatedPosts = await getEntries(data.relatedPosts);
+---
+
+<h1>{blogPost.data.title}</h1>
+<p>Authors: {authors.map(a => a.data.name).join(', ')}</p>
+
+<!-- ... -->
+
+<h2>You might also like:</h2>
+{relatedPosts.map(p => (
+  <a href={p.slug}>{p.data.title}</a>
+))}
+```
+
+### Filtering collection queries
 
 `getCollection()` takes an optional "filter" callback that allows you to filter your query based on an entry's `id`, `slug`, or `data` (frontmatter) properties.
 
-You can use this to filter by any content criteria you like. For example, you can filter by frontmatter properties like `draft` to prevent any draft blog posts from publishing to your blog:
+:::note
+The `slug` property is specific to content collections, and will not be available when filtering collections of JSON or YAML.
+:::
+
+You can use this to filter by any content criteria you like. For example, you can filter by properties like `draft` to prevent any draft blog posts from publishing to your blog:
 
 ```js
-// Example: Filter content entries with `draft: true` frontmatter
+// Example: Filter content entries with `draft: true`
 import { getCollection } from 'astro:content';
 const draftBlogEntries = await getCollection('blog', ({ data }) => {
   return data.draft !== true;
@@ -342,16 +445,16 @@ const { post } = Astro.props;
 
 ### Rendering content to HTML
 
-Once queried, you can render a collection entry to HTML using the entry `render()` function property. Calling this function gives you access to rendered content and metadata, including both a `<Content />` component and a list of all rendered headings.
+Once queried, you can render Markdown and MDX entries to HTML using the entry `render()` function property. Calling this function gives you access to rendered content and metadata, including both a `<Content />` component and a list of all rendered headings.
 
 ```astro {5}
 ---
 // src/pages/render-example.astro
-import { getEntryBySlug } from 'astro:content';
-const entry = await getEntryBySlug('blog', 'post-1');
+import { getEntry } from 'astro:content';
+const entry = await getEntry('blog', 'post-1');
 const { Content, headings } = await entry.render();
 ---
-<p>Written by: {entry.data.author}</p>
+<p>Published on: {entry.data.published.toDateString()}</p>
 <Content />
 ```
 
@@ -391,20 +494,20 @@ This will generate a new page for every entry in the `blog` collection. For exam
 
 ### Building for server output (SSR)
 
-If you are building a dynamic website (using Astro's SSR support), you are not expected to generate any paths ahead-of-time during the build. Instead, your page should examine the request (using `Astro.request` or `Astro.params`) to find the `slug` on-demand, and then fetch it using [`getEntryBySlug()`](/en/reference/api-reference/#getentrybyslug). 
+If you are building a dynamic website (using Astro's SSR support), you are not expected to generate any paths ahead of time during the build. Instead, your page should examine the request (using `Astro.request` or `Astro.params`) to find the `slug` on-demand, and then fetch it using [`getEntry()`](/en/reference/api-reference/#getentry).
 
 
 ```astro
 ---
 // src/pages/posts/[...slug].astro
-import { getEntryBySlug } from "astro:content";
+import { getEntry } from "astro:content";
 // 1. Get the slug from the incoming server request
 const { slug } = Astro.params;
 if (slug === undefined) {
 	throw new Error("Slug is required");
 }
 // 2. Query for the entry directly using the request slug
-const entry = await getEntryBySlug("blog", slug);
+const entry = await getEntry("blog", slug);
 // 3. Redirect if the entry does not exist
 if (entry === undefined) {
 	return Astro.redirect("/404");
@@ -429,8 +532,9 @@ This guide shows you how to convert an existing Astro project with Markdown file
     ```ts title="src/content/config.ts"
     // Import utilities from `astro:content`
     import { z, defineCollection } from "astro:content";
-    // Define a schema for each collection you'd like to validate.
+    // Define a `type` and `schema` for each collection
     const postsCollection = defineCollection({
+        type: 'content',
         schema: z.object({
           title: z.string(),
           pubDate: z.date(),
@@ -564,7 +668,7 @@ This guide shows you how to convert an existing Astro project with Markdown file
     ```
 
     :::note
-    Any individual Markdown or MDX file imports should be replaced by [`getEntryBySlug()`](/en/reference/api-reference/#getentrybyslug).
+    Any individual Markdown or MDX file imports should be replaced by [`getEntry()`](/en/reference/api-reference/#getentry).
     :::
 
 8. Update the code that uses the publish date in the `layouts/MarkdownPostLayout.astro` file.
@@ -619,8 +723,8 @@ Astro supports remark or rehype plugins that [modify your frontmatter directly](
 
 ```astro "{ remarkPluginFrontmatter }"
 ---
-import { getEntryBySlug } from 'astro:content';
-const blogPost = await getEntryBySlug('blog', 'post-1');
+import { getEntry } from 'astro:content';
+const blogPost = await getEntry('blog', 'post-1');
 const { remarkPluginFrontmatter } = await blogPost.render();
 ---
 <!-- 
@@ -631,5 +735,5 @@ const { remarkPluginFrontmatter } = await blogPost.render();
 <p>{blogPost.data.title} — {remarkPluginFrontmatter.readingTime}</p>
 ```
 
-The remark and rehype pipelines only runs when your content is rendered, which explains why `remarkPluginFrontmatter` is only available after you call `render()` on your content entry.  In contrast, `getCollection()` and `getEntryBySlug()` cannot return these values directly because they do not render your content.
+The remark and rehype pipelines only runs when your content is rendered, which explains why `remarkPluginFrontmatter` is only available after you call `render()` on your content entry.  In contrast, `getCollection()` and `getEntry()` cannot return these values directly because they do not render your content.