File Loader API unclear

[JusticeMatthew]

📚 Subject area/topic

Content Loader API

📋 Page(s) affected (or suggested, for new content)

https://docs.astro.build/en/reference/content-loader-reference/#file-loader

📋 Description of content that is out-of-date or incorrect

Currently the file() loader API reference contains this line:

The file() loader creates entries from a single file that contains an array of objects with a unique id field, or an object with string keys.

What this line leaves out is that if you do use an object with string keys, the values must also be objects

This caused some confusion when a user attempted to do something like this:

{
  "entry1": "foo",
  "entry2": "bar",
  "entry3": "baz"
}

Which resulted in a schema error expecting an object but receiving a string

🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)

A reproduction was created here by the discord member that brought it to my attention
https://github.com/anmpog/content-collection-issue-repro

[ArmandPhilippot]

Would the wording below have been clearer?

The file() loader creates entries from a single file that contains an array of objects with a unique id field, or an object with IDs as keys and entries as values.

Or, maybe we need to be a bit more verbose and replace what we currently have with something like:

The `file()` loader creates entries from a single file that can be parsed as an array of objects. It supports JSON or YAML, and you can provide a custom parser for data files it cannot parse by default.

An entry must be represented by an object with an ID field or a string key that serves as an ID associated with an object containing the entry's data.

This loader accepts a fileName property and an optional object as second argument:

[JusticeMatthew]

Personally I think the first would be just fine, that makes it very clear to me

I'll mention it to the user that I was working with on this too and have them comment if they get a chance 👍

[Fermain]

I am experiencing this coming from v4, there is no mention in the migration guide as far as I can see:

https://docs.astro.build/en/guides/upgrade-to/v5/#updating-existing-collections

A short example of how this should look would go a long way, I assumed that I could port and existing file collection to v5 without issue.

Even after changing the shape of the file to use string key + object value, I am not able to use this feature successfully.

[ArmandPhilippot]

Hi @Fermain!

You're right, the migration guide doesn't show how to use the file() loader because this is a new feature. I don't remember single files being supported in v4 (but I could be wrong, I mostly use v5 since the beta...). So we can't really show an example in the migration guide...
We only show the glob() loader because it matches the previous behavior. So, for a data collection, type: "data" is replaced with loader: glob() and instead of .md files you load .json files.

The file() loader is used to create a collection from a single file. It's hard to show an example what a file should look like since the loader accepts different file formats (JSON, YAML, and even other file formats with a custom parser)... But an authors.json file could look like:

{
  "john-doe": {
    "firstName": "John",
    "lastName": "Doe",
  },
  "jane-doe": {
    "firstName": "Jane",
    "lastName": "Doe",
  }
}

This is the same as an authors directory containing john-doe.json and jane-doe.json loaded with glob() but here, they are gathered in the same file.

If you're on Discord, do not hesitate to create a support thread so someone can help you migrating your collections. Otherwise, you can also ask for help on Astro Support Squid.