feat: experimental content collection JSON schemas

.changeset/slow-items-heal.md

@@ -0,0 +1,38 @@
+---
+"astro": minor
+---
+
+Adds experimental JSON Schema support for content collections of with `type: 'data'`.
+
+To enable this feature, add the experimental flag:
+
+```diff
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+	experimental: {
++		contentCollectionJsonSchema: true
+	}
+});
+```
+
+To make sure VSCode picks up the schema file, you have multiple option. You can either reference the file in every file of your content collection:
+```diff
+{
++  "$schema": "../../../.astro/schemas/collections/test.json",
+  "test": "test"
+}
+```
+
+Or you can set your VSCode settings to match them, read more in the [VSCode docs](https://code.visualstudio.com/docs/languages/json#_json-schemas-and-settings):
+
+```diff
+"json.schemas": [
+  {
+    "fileMatch": [
+      "/src/content/test/**"
+    ],
+    "url": "../../../.astro/schemas/collections/test.json"
+  }
+]
+```

packages/astro/package.json

@@ -176,7 +176,8 @@
     "vitefu": "^0.2.5",
     "which-pm": "^2.1.1",
     "yargs-parser": "^21.1.1",
-    "zod": "^3.22.4"
+    "zod": "^3.22.4",
+    "zod-to-json-schema": "^3.22.4"
   },
   "optionalDependencies": {
     "sharp": "^0.32.6"

packages/astro/src/@types/astro.ts

@@ -1640,6 +1640,25 @@ export interface AstroUserConfig {
 		 */
 		contentCollectionCache?: boolean;
 
+		/**
+		 * @docs
+		 * @name experimental.contentCollectionJsonSchema
+		 * @type {boolean}
+		 * @default `false`
+		 * @version 4.5.0
+		 * @description
+		 * Enables generation of JSON Schema files for content collections of type `data`.
+		 *
+		 * ```js
+		 * {
+		 * 	experimental: {
+		 * 		contentCollectionJsonSchema: true,
+		 * 	},
+		 * }
+		 * ```
+		 */
+		contentCollectionJsonSchema?: boolean;
+
 		/**
 		 * @docs
 		 * @name experimental.clientPrerender

packages/astro/src/content/types-generator.ts

@@ -4,6 +4,8 @@ import type fsMod from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { normalizePath, type ViteDevServer } from 'vite';
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
 import type { AstroSettings, ContentEntryType } from '../@types/astro.js';
 import { AstroError } from '../core/errors/errors.js';
 import { AstroErrorData } from '../core/errors/index.js';
@@ -310,6 +312,8 @@ export async function createContentTypesGenerator({
 				contentConfig: observable.status === 'loaded' ? observable.config : undefined,
 				contentEntryTypes: settings.contentEntryTypes,
 				viteServer,
+				logger,
+				settings,
 			});
 			invalidateVirtualMod(viteServer);
 		}
@@ -352,6 +356,8 @@ async function writeContentFiles({
 	contentEntryTypes,
 	contentConfig,
 	viteServer,
+	logger,
+	settings,
 }: {
 	fs: typeof fsMod;
 	contentPaths: ContentPaths;
@@ -360,9 +366,19 @@ async function writeContentFiles({
 	contentEntryTypes: Pick<ContentEntryType, 'contentModuleTypes'>[];
 	contentConfig?: ContentConfig;
 	viteServer: Pick<ViteDevServer, 'hot'>;
+	logger: Logger;
+	settings: AstroSettings;
 }) {
 	let contentTypesStr = '';
 	let dataTypesStr = '';
+
+	const collectionSchemasDir = new URL('./schemas/collections/', contentPaths.cacheDir);
+	if (settings.config.experimental.contentCollectionJsonSchema) {
+		if (!fs.existsSync(collectionSchemasDir)) {
+			fs.mkdirSync(collectionSchemasDir, { recursive: true });
+		}
+	}
+
 	for (const [collection, config] of Object.entries(contentConfig?.collections ?? {})) {
 		collectionEntryMap[JSON.stringify(collection)] ??= { type: config.type, entries: {} };
 	}
@@ -419,6 +435,36 @@ async function writeContentFiles({
 				for (const entryKey of Object.keys(collection.entries).sort()) {
 					const dataType = collectionConfig?.schema ? `InferEntrySchema<${collectionKey}>` : 'any';
 					dataTypesStr += `${entryKey}: {\n	id: ${entryKey};\n  collection: ${collectionKey};\n  data: ${dataType}\n};\n`;
+					if (
+						settings.config.experimental.contentCollectionJsonSchema &&
+						collectionConfig?.schema
+					) {
+						let zodSchemaForJson = collectionConfig.schema;
+						if (zodSchemaForJson instanceof z.ZodObject) {
+							zodSchemaForJson = zodSchemaForJson.extend({
+								$schema: z.string().optional(),
+							});
+						}
+						try {
+							await fs.promises.writeFile(
+								new URL(`./${collectionKey.replace(/"/g, '')}.json`, collectionSchemasDir),
+								JSON.stringify(
+									zodToJsonSchema(zodSchemaForJson, {
+										name: collectionKey.replace(/"/g, ''),
+										markdownDescription: true,
+										errorMessages: true,
+									}),
+									null,
+									2
+								)
+							);
+						} catch (err) {
+							logger.warn(
+								'content',
+								`An error was encountered while creating the Json schema. Proceeding without it. Error: ${err}`
+							);
+						}
+					}
 				}
 				dataTypesStr += `};\n`;
 				break;

packages/astro/src/core/config/schema.ts

@@ -60,6 +60,7 @@ const ASTRO_CONFIG_DEFAULTS = {
 	experimental: {
 		optimizeHoistedScript: false,
 		contentCollectionCache: false,
+		contentCollectionJsonSchema: false,
 		clientPrerender: false,
 		globalRoutePriority: false,
 		i18nDomains: false,
@@ -492,6 +493,10 @@ export const AstroConfigSchema = z.object({
 				.boolean()
 				.optional()
 				.default(ASTRO_CONFIG_DEFAULTS.experimental.contentCollectionCache),
+			contentCollectionJsonSchema: z
+				.boolean()
+				.optional()
+				.default(ASTRO_CONFIG_DEFAULTS.experimental.contentCollectionJsonSchema),
 			clientPrerender: z
 				.boolean()
 				.optional()