Add deleted section about json schema generation

[alexanderniebuhr]

Description (required)

• This PR readds an section which was deleted by accident
• Initial release was in feat: add docs for json schemas #8705
• It got removed in Revamp Content section 5.0 #9328

Related issues & labels (optional)

• needed for Fix file() loader JSON schema astro#14221
• needed for file loader produces incorrect json schema astro#13536

[netlify]

✅ Deploy Preview for astro-docs-2 ready!

Name	Link
🔨 Latest commit	310e4ce
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/68a37a2ec6b70c00082f9633
😎 Deploy Preview	https://deploy-preview-12155--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[astrobot-houston]

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File	Note
en/guides/content-collections.mdx	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

[ArmandPhilippot]

LGTM! I only left a fix (the config file) and two nits regarding paths.

[bjohansebas]

I’ve been thinking about this for quite a while. I wonder which data-type collections could benefit from this, only .json? If it’s only JSON file collections, I think it would be better to say that it only benefits them instead of implying it’s more global.

Or, if this benefits more globally, like .yaml or .toml files, since those would be data-type collections (as far as I understand, I could be wrong), then improving the meaning of that “data-type collections” concept would work here, because I find it a bit confusing.

Just my two cents.

[ArmandPhilippot]

Nice catch, thanks! This is indeed the wording used with the previous API where data was a collection type. So we probably need to reword this part to clarify what a data collection is.

I quickly tested on my side, and the schema auto-generation works for JSON, YAML and TOML files. But now, I'm a bit confused because I tried with a collection using Markdown files and a JSON schema is also generated for those (e.g. .astro/collections/posts.schema.json). Which contradicts what we have in Experimental Intellisense for content collections:

When enabled, this feature will generate and add JSON schemas to the .astro directory in your project.

It seems the JSON schemas are always generated (for any file supported at least).
EDIT: However, it seems the .astro/collections/collections.json is only generated with the experimental flag enabled.

However, I guess there is no native support for validating a YAML or TOML file with a JSON schema (please correct me if I'm wrong) and, so, what is described here only work when using a JSON file. This can be extended to .md, .mdx and .mkdoc files using the experimental flag. Now, the grey zone to me is... is there a way to provide Intellisense to YAML and TOML file with a JSON schema?

And maybe we should rework this section to precise that the schema must be provided manually and:

• this is supported by default for JSON files,
• for .md, .mdx and .mkdoc, the user needs to enable the experimental flag
• figure out what can be done with YAML and TOML

[alexanderniebuhr]

It does not only affect .json files, it also works for .yaml files for example

[ArmandPhilippot]

Oh okay, I thought YAML required to install something to be able to do that doing a very quick research. So, if it's supported by default, I guess we need to verify if TOML is also supported, because it was added more recently, or if we need to precise this only applies to JSON and YAML.

[alexanderniebuhr]

Well it depends on how your Editor handles it. But yeah for VSCode you need the redhat extension for "full yaml lsp" support. But other editors might have it built in. We shouldn't be editor specific here I think though.

I don't want this PR to look like it's ready to go when we still need to figure out how to improve that section because of API changes since its removal.

[sarah11918]

Will note that on Talking and Doc'ing last week, we briefly discussed where on the page this information makes sense to add because to this is does not fall under any of the existing 3 topics (Defining the collection, querying the collection generating routes from the collection) but is also not really "on the same hierarchy level" as those broad topics.

This is related to the file loader, but instead something (more advanced?) that you do with a collection entry, and in fact, maybe is in some way related to the <h3> "defining a custom ID" in that sense.

I think @delucis will be overseeing this PR, alongside and dependent upon his feature fix PR. So I wouldn't treat this as "ready to review" since it's not even correct content yet. It's just a cut and paste placeholder from the way collections worked pre-v5 right now (e.g. there is no type for collections anymore), but should be considered more like feature documentation to accompany the incoming PR.

We'll need to document how it's supposed to work with the content layer API now powering collections: does this only affect the file() loader loading a single JSON file, or also glob() if there are multiple JSON files for each entry? (The example here looks like the file is a single author, not an "authors" file? If we mean for this to be strictly a "one JSON file collection" then I think we might want the code example to show multiple author entries in the single file, and not be named after one author?) Does this only work for local JSON entries? (not remote JSON files that might be using a custom loader instead of our built-in loaders, but still loading and parsing JSON?)

There were a lot of things that were unclear about how this worked for new content collections when they were released in v5, which is why this section was removed at that time! It wasn't actually deleted by accident, but we didn't have confirmation for how this content needed to be updated at the time, so we could not include it. We instead went with the assumption that if this is still a thing, it will make itself an issue at some future date. THE FUTURE IS NOW! 😄

[alexanderniebuhr]

does this only affect the file() loader loading a single JSON file, or also glob() if there are multiple JSON files for each entry?

Does affect both :)