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?

[edolstra]

Shouldn't other commands go through the schema?

No, the schemas reflect what those commands do (e.g. the nixosConfigurations schema reflects that nixos-rebuild requires a config.system.build.toplevel attribute that evaluates to a derivation), they don't determine what those commands do.

In the future, some commands could use schemas, e.g. nix build .#nixosConfigurations.my-machine could use the nixosConfigurations schema to figure out that it needs to expand my-machine to my-machine.config.system.build.toplevel. That would be pretty nice.

Continuing the previous point, we have an opportunity to clarify the meanings of the various attributes - specifically whether they related to the build or host system (or target - probably rare and to be avoided)

Assigning a meaning to system attributes is up to the schemas. E.g. if some tool has a more refined notion of system types, the corresponding schema could check those types.

Explore what can be un-hardcoded from Nix. Perhaps logic from src/nix/call-flake-schemas.nix could be moved into the schemas repo?

call-flake-schemas.nix is a fairly minimal bit of helper code to evaluate schemas. It's completely internal to nix::flake_schemas::call(). It could be done in C++, but that would be more code.

Give inventory a static counterpart that declares something about the contents without having them, as schemas do. This is important for discoverability.

Schemas already have some static info (like a doc attribute). However, statically declaring what the contents should look like sounds like a type system, which is a much bigger project. The flake schema format is extensible so it could support that though.

[roberth]

Discussed in the meeting today. We didn't have a lot of time because we were towards the end of it, so I'll just summarize the thoughts I shared.

Naming

• "Schemas" has a fairly well-defined meaning in software that doesn't quite align with this. Perhaps we could change the name. We've considered "flake protocols" (similarly vague and not a massive improvement), "flake interfaces" (might interfere with potential terminology for Nix types we might have at some point) and "flake descriptors" (worth considering?)
• Schemas may evolve into types when that happens. I think it would be good to change the name at that point, because that's a significant change, and they could coexist (certainly during a "migration" phase)

Is it possible to export a flake schema into a serializable form? (Or documentation)

• It could evolve to support that?
• It'd be beneficial to have an expression-level indirection that mediates between users and a minimal Nix<->expressions interface. This indirection would feel similar to the module system, but users would write even fewer lambdas. It could live in the flake-schemas repo.
  • Similar to a mkDerivation or a libc (in Nix at least where you can have multiple libcs). This layer provides ease of use to take the pressure of the kernel (ie Nix's C++ code) to incorporate conveniences that need to evolve over time.
  • Also allows the extension of the Nix<->expressions interface. For instance support for outputting a serializable schema or documentation would be a matter of Nix calling .schema or .docs instead of .check.
    • Ie docs is an attribute that the flake schemas repo synthesizes from the individual doc attributes it processes.
  • Would be usable without Nix assigning semantics to those attributes on the schema attrsets
• Users could still talk to the low level Nix<->expressions interface directly, but they wouldn't get the benefits from the flake schemas repo indirection. I don't think that's a problem; just a missed opportunity for them.

[shivaraj-bh]

Apart from recognising what, shortDescription and derivation as the leaf types, it would be nice to also recognise arbitrary values in the configuration.

Perhaps like:

From 1d23c1e871981f5666a12c4409bd0574fc1e1e02 Mon Sep 17 00:00:00 2001
From: shivaraj-bh <[email protected]>
Date: Wed, 21 Aug 2024 15:14:03 +0530
Subject: [PATCH] support value as leaf node

---
 src/nix/flake.cc | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/src/nix/flake.cc b/src/nix/flake.cc
index f470d847bf8..6960a3e9e89 100644
--- a/src/nix/flake.cc
+++ b/src/nix/flake.cc
@@ -18,6 +18,7 @@
 #include "markdown.hh"
 #include "users.hh"
 #include "flake-schemas.hh"
+#include "value-to-json.hh"
 
 #include <nlohmann/json.hpp>
 #include <queue>
@@ -782,6 +783,13 @@ struct CmdFlakeShow : FlakeCommand, MixJSON, flake_schemas::MixFlakeSchemas
                         if (auto drv = flake_schemas::derivation(leaf))
                             obj.emplace("derivationName", drv->getAttr(state->sName)->getString());
 
+                        // TODO: Add a function in flake-schemas.hh to handle this
+                        if (auto value = leaf->maybeGetAttr("value")) {
+                            auto v = value->forceValue();
+                            NixStringContext context;
+                            obj.emplace("value", printValueAsJSON(*state, true, v, noPos, context, false));
+                        }
+
                         // FIXME: add more stuff
                     },
 

If this is out of scope of this PR, I could raise a separate PR after this is merged, describing the use-case in more detail.

[PedroHLC]

Is there any rebased version of this branch?