Use zod to define the schema of a single json file, similar to defining a collection schema, but for 1 json file

[godalming123]

Body

Summary

Be able to use zod to define the schema of a single json file at a time within astro.config.mjs, similar to https://docs.astro.build/en/guides/content-collections/#defining-a-collection-schema but for 1 json file.

Background & Motivation

For some websites (such as simple portfolios), it is useful to be able to define all of the content within one file, and then the whole website can be updated by simply editing the file and waiting for some automated tool to build it. To achieve this, a src/content.json file could be used and used like so:

import content from '../data/content.json';
const { websiteName, websiteDescription } = content;

But this approach would not allow the use of astro's image component because to do that you have to have a image object that has been imported. To fix this you could place the file in a content collection, but that's pretty hacky since a content collection is designed for multiple files. One proposal (#785) would allow a content collection to be represented as a single file, but that would not allow a propeties like "websiteName" or "websiteDescription" to be specified in the root of the collection as far as I am aware.

Goals

All of the following should only apply on a per-file basis:

• Have clear build-time error messages when a json file does not fulfil a specified criteria
• Type-checking when using a json file in typescript
• Astro image components that get their source from a json file

Example

Note: withastro/astro/pull/9850/ (the PR to implement this API) has lots of discussion about different API ideas.

Defining the type checking for the file:
astro.config.mjs

const contentFile = defineJsonDataFile({
  path: "src/content.json",
  schema: z.object({
    websiteName: z.string(),
    websiteDescription: z.string(),
    websiteFrontImage: image(),
  }),
});

export default defineConfig({
  jsonDataFiles: [
    contentFile
  ]
});

Defining the file:
src/content.json

{
  "websiteName": "Some website name",
  "websiteDescription": "Some description",
  "websiteFrontImage": "./content/images/1.jpg"
}

Using the file:
src/pages/index.astro

---
import content from '../data/content.json';
import { Image } from 'astro:assets'
---

<h1>{content.websiteName}</h1>
<p>{content.websiteDescription}</h1>
<Image src={content.websiteFrontImage } />

[florian-lefebvre]

Yes, I think singletons support would be great

[godalming123]

@florian-lefebvre, as a contributor who seems interested in this feature, would you mind helping me with my pull request to implement it? On this line I need to convert the relative path into an absolute path so that it can be detected when a JSON file that has a validation schema is imported on this line. Any ideas?

[florian-lefebvre]

I am not familiar with this part of the codebase and I have other plans for now, sorry about that! First, I think you should come in the #dev channel on the Discord server (https://astro.build/chat) and see what's the best way of doing this. What I mean is that since this is likely a minor, you may need to go through a proper RFC process to see what's the best API etc. Feel free to ask on that channel!

[bluwy]

Nate has already commented on this idea at withastro/astro#9850 (review), but to leave my thoughts here, I think this should be left to content collections as well. Or at least via a third-party integration.

You can create a Vite plugin that handles loading specific JSON files and validate them with zod for example.