feat: experimental content collection JSON schemas

[alexanderniebuhr]

Changes

• initial implementation of IntelliSense for Content Collection JSON roadmap#696
• the implementation does not handle automatic inserting of schemas into files for lsp to pick that up
• using this implementation JSON should be supported, and yaml should be supported if user used redhats yaml vscode extension
• implementation using an experimental flag, to test things out

import { defineConfig } from 'astro/config';

export default defineConfig({
	experimental: {
+		contentCollectionJsonSchema: true
	}
});

• first caveat, the used library has known issues for advanced zod schemas (https://github.com/StefanTerdell/zod-to-json-schema#known-issues)
• second caveat, users have to allow $schema property in their zod schema, otherwise they get a warning

import { defineCollection, z } from 'astro:content';

const test = defineCollection({
	type: 'data',
	schema: z.object({
+		"$schema": z.string().optional(),
		test: z.string()
	}),
});

export const collections = { test };

• third caveat, users have to manually reference the schema in their content collection data files

{
+  "$schema": "../../../.astro/schemas/collections/i18n.json",
  "homepage": {
    "greeting": "ME",
    "preamble": "ME"
  }
}

Testing

• not added any tests yet, since we would most likely need some snapshot tests 🤔

Docs

• I think the config reference is pulled automatically for the experimental flag
• unsure whether we need docs &or where we would document experimental features (cc @sarah11918)

[changeset-bot]

🦋 Changeset detected

Latest commit: 413bafd

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[alexanderniebuhr]

• feat: experimental content collection JSON schemas #10145 👈
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

Join @alexanderniebuhr and the rest of your teammates on Graphite

[github-actions]

This PR is blocked because it contains a minor changeset. A reviewer will merge this at the next release if approved.

[natemoo-re]

Looks great! Have a few suggestions still, but not blocking so I'm preemptively approving.

[natemoo-re]

Nice, this seems like a reasonable way to handle it!

[sarah11918]

Thanks for this @alexanderniebuhr ! Left some things to think about for the changeset, which will then take us on to the actual docs content!

Because this is experimental, we typically would not mention it in docs on e.g. the content collections page. So, we don't need another docs PR, because this should be the only place it appears while experimental! 🙌

[sarah11918]

"Once the changeset is figured out, those instructions, limitations etc should also be here! This is the place in docs where people will go to figure out what this does and how it works!

When we like the changeset, it can be a mostly copy-paste here, except that this can be less "here's a new feature!" and more just boring, "here's what you do."

Reminder to self: this should also link to the content collections page in docs.

[alexanderniebuhr]

Not sure if this warning also needs rewording. If so please feel free to commit that yourself.

[sarah11918]

JSON is probably all caps when referred to as a name/noun?

[alexanderniebuhr]

According to https://json-schema.org/ yes, so I've updated the warning message

[sarah11918]

I think just some tiny nits to clean up here, otherwise, LGTM!

Merge day