Flake schemas

[edolstra]

Motivation

A big problem with current flakes is that commands like nix flake check and nix flake show have built-in support for a limited set of flake output types. For instance, they know about nixosConfigurations but not homeConfigurations.

This PR moves support for flake output types out of C++ and into Nix functions supplied by a new schemas flake output. This allows users to define their own flake output types, and have them show up in nix flake show and checked by nix flake check. As a result, there are no more flake output types that are more "blessed" than others.

There is no central registry of schemas. Instead a flake should add an appropriate schemas flake output for the outputs it wants to have checked. Typically this will include schemas from other flakes. In particular, I've made a flake-schemas flake with schemas for the flake output types that were previously built into Nix.

The format of schemas is documented in doc/manual/src/protocols/flake-schemas.md.

To do:

• The evalChecks schema attribute need to be refined to allow checkers to return warnings/errors in a more sensible way than an assertion failure.

Context

Fixes #3487, #6453, #6454.

Checklist for maintainers

Maintainers: tick if completed or explain if not relevant

• agreed on idea
• agreed on implementation strategy
• tests, as appropriate
  • functional tests - tests/**.sh
  • unit tests - src/*/tests
  • integration tests - tests/nixos/*
• documentation in the manual
• documentation in the internal API docs
• code and comments are self-explanatory
• commit message explains why the change was made
• new feature or incompatible change: updated release notes

Priorities

Add 👍 to pull requests you find important.

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/flake-schemas-making-flake-outputs-extensible/32421/1

[NobbZ]

If I understand the description correctly, this would also solve #6453 and #6454.

[samueldr]

Shouldn't this be owned by the NixOS organization?

[edolstra]

Definitely, if this PR gets accepted.

[samueldr]

What does FIXME mean here for schemaOverrides?

[edolstra]

This was intended to support adding/overriding (some) schemas from the command line, but I didn't implement that yet.

[roberth]

Considering that the schema returns the children, this defines a new "derivation" centric, tree shaped view of the flake that is determined by the flake itself, as the flake defines the schema. Shouldn't other commands go through the schema then? Otherwise, we are still making assumptions about the schema contents.

Should the evaluated schema be exposed to flakes that consume the flake as an input?

Do we need the interface between the CLI and the flake need to be schema-like? Why don't we expose the desired functionality directly by defining one or two new outputs that don't rely on the concept of a schema? For example:

outputs = inputs@{ self, ... }: {
  evalChecks = {
    myChecks = ...;
    fooChecks = inputs.foo.lib.evalChecks self;
  };

  treeView = {
    hasPackage = 1;
    children = {
      defaultPackage = { # picked this simpler one for brevity. Users won't write this by hand, just as they generally don't write schemas
        children = {
          isDict = true;
          role = "system";
          children = {
            x86_64-linux = {
              isPackage = true;
              value = ...;
            };
          };
        };        
      };
    };
  };
}

Outputs like this seem conceptually simpler to me, and they seem easier to use from within the language.

They will be similarly easy to use when the outputs are defined through a library.
Considering that the flake-schemas repo is already a library, this condition holds.

If we do decide that we need a concept of schema, is the metaschema as simple as it can be, or can it leverage more of the language?

[KevinCathcart]

Considering that the schema returns the children, this defines a new "derivation" centric, tree shaped view of the flake that is determined by the flake itself, as the flake defines the schema. Shouldn't other commands go through the schema then? Otherwise, we are still making assumptions about the schema contents.

I didn't think this is intended to be a new view of the flake at all. And it is absolutely not intended to be derivation centric. The real concept being embodied is conceptual outputs that user care about. That is to say: packages, modules, checks, configurations, ci jobs, overlays, deployment definitions, etc. These big picture concept that people would generally hope would show up in nix flake show output. Of course, some of them may be smaller picture items too, like a library flake's conceptual outputs are the library functions it exports. We don't have a great name for these conceptual outputs, so I will use "artifact" for them.

The problem, of course, is that there is no simple way to enumerate these artifacts. It is not like these are all top level output attributes. Indeed, they pretty deliberately are mostly not top level attributes, since having some structure makes it possible for tooling to distinguish outputs in useful ways. Most standard output attributes are either attribute sets of these, or attribute sets of attribute sets of these. In practice these artifacts are almost always just nix values that can be reached as an attribute path from output attribute set.

Given that in practice in order to use any of these artifacts you need to know how to reference them from an imported flake, it would really make no sense to have the schema define a different tree structure then the output's attributes already have, albeit truncated.

Do we need the interface between the CLI and the flake need to be schema-like? Why don't we expose the desired functionality directly by defining one or two new outputs that don't rely on the concept of a schema? For example:
...
Outputs like this seem conceptually simpler to me, and they seem easier to use from within the language.

This is a possibility. From a flake authoring perspective, importing evalchecks sounds like a fairly low level thing to be working with, while importing a schema from a flake and assigning that sounds more high level. Similarly from an authoring perspective to add a new schema would be schemas = flake-schemas.schemas // other-schemas.schemas; but with this approach, I'd need to not only do something similar for eval checks, but also need to compose the standard attributes treeview generating function with the one for the community defined output type and assign that. Doable, but just more boilerplate, and there is already more boilerplate stuff with flakes than many people like.

[roberth]

I didn't think this is intended to be a new view of the flake at all.

I agree about the intent, but it's the details of the design that matter.
The children attribute does seem to form a view of the flake, which could be expressed more simply as another output attribute.

It is worth repeating that Nix is highly constrained when it comes to making changes, because we've successfully provided compatibility with old expressions, and would like to keep that unique property. While this doesn't apply during the experimental phase of a feature, we will eventually have to judge it by the usual standard before we can call it stable.
So a feature like this could further delay the stabilization of flakes if it isn't as simple as it could be.

Another important observation is that the less we do in C++ and the more we do in Nix expressions, we get better opportunities to iterate on our solutions, because users can pin or lock such expressions and adapt to any changes at their own pace, or not at all if we're talking about support for old expressions.

Hence I'd take a PR that reifies CLI behavior as an expression-based interface over a PR that introduces new concepts any day - as long as it's clear what the CLI should do, and in case of enumerating and checking that seems rather clear. Extensions to that behavior can be represented by following the dict vs record pattern we've described in the JSON guideline (applied to attrsets instead).

[srid]

Some outputs are not technically a derivation, but rather a path, yet they are paths referring to the output of a derivation. apps.*.program for example. How can they be represented in this schema?

Ref: DeterminateSystems/flake-schemas#5

[aanderse]

any update on this? i don't think i saw any mention of this on any of the team meetings i glanced through recently

[grahamc]

For what it’s worth we’re using them a lot at determinate systems to good effect.

…

On Sat, Feb 24, 2024, at 10:07 AM, Aaron Andersen wrote: any update on this? i don't think i saw any mention of this on any of the team meetings i glanced through recently — Reply to this email directly, view it on GitHub <#8892 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAASXLEZJUVWTZZFGZSEOX3YVH63XAVCNFSM6AAAAAA4GIL65OVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSNRSGM4TMNJXGM>. You are receiving this because you commented.Message ID: ***@***.***>

[sellout]

For what it’s worth we’re using them a lot at determinate systems to good effect.

I’ve also had success with them. Here’s a fairly rich schema I use in most of my projects: https://github.com/sellout/project-manager/blob/495cb847eb2cbf6b7981576c3b1610cc077c4768/nix/schemas.nix#L6-L80

[aanderse]

sounds lovely

i wonder what it would take to move forward with this

[adamcstephens]

For what it’s worth we’re using them a lot at determinate systems to good effect.

That's great to hear. What is the status of y'all moving this forward?

[MattSturgeon]

Forgive my ignorance, but how are people using schemas without the nix command supporting them?

Or are people running a build of this PR branch instead of upstream?

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/determinate-nix-3-0/61202/66