Support YAML validation for `metadata-files` used in `_quarto.yml`

[cderv]

Discussed in https://github.com/quarto-dev/quarto-cli/discussions/8396

^{Originally posted by **anielsen001** January 23, 2024} ### Description I'm trying to merge some sidebar information from a metadata-files with an existing _quarto.yml file. my _quarto.yml looks like this: ```yaml project: type: website metadata-files: - _sidebar.yml website: title: "Test-sidebar" navbar: left: - href: index.qmd text: Home - about.qmd sidebar: style: docked format: html: theme: cosmo css: styles.css toc: true ``` and the _sidebar.yml file looks like this: ```yaml website: sidebar: - contents: - index.qmd - about.qmd ``` when I do this, I get a docked style sidebar, but it's empty. If I comment out the sidebar information in the _quarto.yml, I get the sidebar information from the _sidebar.yml file. The [docs](https://quarto.org/docs/projects/quarto-projects.html#metadata-includes) indicate that these should merge, but maybe I'm misunderstanding. What's the expected behavior here? Heres my quarto check out put ```bash$ quarto check Quarto 1.4.533 [✓] Checking versions of quarto binary dependencies... Pandoc version 3.1.11: OK Dart Sass version 1.69.5: OK Deno version 1.37.2: OK [✓] Checking versions of quarto dependencies......OK [✓] Checking Quarto installation......OK Version: 1.4.533 Path: /opt/quarto/bin [✓] Checking tools....................OK TinyTeX: (not installed) Chromium: (not installed) [✓] Checking LaTeX....................OK Using: Installation From Path Path: /usr/bin Version: 2019 [✓] Checking basic markdown render....OK [✓] Checking Python 3 installation....OK Version: 3.8.3 Path: /home/apn/sw/bin/python3 Jupyter: 4.10.0 Kernels: julia-1.8, python3 [✓] Checking Jupyter engine render....OK [✓] Checking R installation...........OK Version: 4.3.2 Path: /usr/lib/R LibPaths: - /home/apn/R/x86_64-pc-linux-gnu-library/4.3 - /usr/local/lib/R/site-library - /usr/lib/R/site-library - /usr/lib/R/library knitr: 1.43 rmarkdown: 2.24 [✓] Checking Knitr engine render......OK ```

[cderv]

From @dragonstyle comments in #8396

I think we're not expecting the sidebar definition in the _sidebar.yml file to be an array- it should be an object (...)

I think the use of metadata-files must be dodging validation somehow... It would be ideal if that would also throw a validation error.

[cscheid]

I think we have an open bug for this somewhere. This is pretty hard to do in general because this mixes validation and "yaml creation". It's the same bug as "we should validate _metadata.yml somehow", but the problem is that the validation of this file is dependent on the files that load it.

[cderv]

but the problem is that the validation of this file is dependent on the files that load it.

could there be a middle ground where only the schema type of content in the metadata-files provided is check ? This would have avoided providing an array instead of an object.

This would not be perfect, but if possible, this would be a first level to validate the file statically like we do a _quarto.yml maybe?

Just idea - Best effort to improve user's experience.

[cscheid]

could there be a middle ground where only the schema type of content in the metadata-files provided is check ? This would have avoided providing an array instead of an object.

Not really, because it's a similar problem to the one I alluded:

but the problem is that the validation of this file is dependent on the files that load it.

The resolution of metadata-files happens after the YAML is loaded, in the same way that the merging of _metadata.yml happens after the YAML document block is loaded.

In order to solve this problem, we would have to write a spec for the precise way and time in which validation happens. It would freeze the semantics of metadata in a way that I'm not ready to commit to yet. Maybe in a couple of years we could do that.

It's a really thorny problem.

[cderv]

I understand better now. Thanks.

So validation and error at rendering is not an easy problem.

In my mind, that leaves us with linters in IDE. Not dependent on us directly, but probably a little as we provide the information. This may be a wild thought, but if an IDE (like VSCODE with our extension, our RStudio IDE) has a way to mark some YAML as "this yaml should respect quarto config schema", it could be a solution to inform users of malformed YAML - even if quarto render won't do anything because of what mentioned before. Linting information is already showing for _quarto.yml so could be also working for other if IDE allows it. 🤷‍♂️

My last thought on this 😅

[machow]

Wait--this is not true:

I think we're not expecting the sidebar definition in the _sidebar.yml file to be an array- it should be an object (...)

Here's an example from the quarto docs:

  sidebar:
    - id: tutorials
      title: "Tutorials"
      style: "docked"
      background: light
      collapse-level: 2
      contents: 
        # navigation items

    - id: howto
      title: "How-To"
      contents:
        # navigation items

    - id: fundamentals
      title: "Fundamentals"
      contents: :
        # navigation items

    - id: reference
      title: "Reference"
      contents: 
        # navigation items

edit: ah wait nevermind -- maybe that's referring to the expectation, based on what sidebar entry is in the _quarto.yml (an object)