An interface change for flake schemas

We at Determinate Systems recently announced the release of flake schemas in Determinate Nix. We’re confident that they make Nix flakes substantially more flexible and introspectable, and we’re eager to see Nix developers expand the range of what flakes provide by introducing brand new schemas into the ecosystem.

We’re also committed to providing an intuitive, fluid developer experience around flakes. On the basis of extensive internal experimentation and early user feedback, we’ve decided to push through a fairly significant change in how schemas work.

Why a change is necessary

The issue we identified is that the schemas output currently fulfills two roles:

1. It tells Nix how the flake’s outputs are structured (packages, devShells, checks, and others).
2. It enables Nix users to share new flake schemas with the world.

We’ve come to the conclusion that these roles are sufficiently distinct that separate flake outputs should fulfill them:

1. The schemas output should do exactly what it does now (inform Nix how the flake’s outputs are structured).
2. Nix developers should use a new exportedSchemas output to introduce flake schemas into the ecosystem.

The fix: two separate outputs

We’ve introduced the exportedSchemas output in 0.5.0 of the flake-schemas flake and recommend using exportedSchemas for non-default schemas beginning now. Here’s an example flake that uses the exportedSchemas output to introduce a new schema called myNewOutput:

{
  inputs = {
    # flake inputs
  };

  outputs =
    { self, ... }@inputs:
    {
      exportedSchemas = {
        myNewOutput = {
          version = 1;
          doc = "The `myNewOutput` flake output.";
          inventory = output: {
            children = builtins.mapAttrs (system: value: {
              forSystems = [ system ];
              what = "special output type";
            }) output;
          };
        };
      };
    };
}

Another flake could then use myNewOutput like this:

{
  inputs = {
    other-flake.url = "github:other-org/other-flake";
    flake-schemas.url = "https://flakehub.com/f/DeterminateSystems/flake-schemas/0";
  };

  outputs =
    { self, ... }@inputs:
    {
      schemas = inputs.flake-schemas.exportedSchemas // inputs.other-flake.exportedSchemas;

      myNewOutput = {
        # outputs that fit this schema
      };

      # other flake outputs
    };
}

The status of the change

Please note that this is not yet a breaking change. Any flakes that are currently using flake-schemas to declare explicit schemas don’t require any immediate updates when upgrading to 0.5.0. But we do recommend updating your flake to use the exportedSchemas output instead of schemas now. Here’s an example diff:

{
  schemas = inputs.flake-schemas.schemas // {
    # new non-default schemas for the ecosystem
  };
  exportedSchemas = {
    # new non-default schemas for the ecosystem
  };

  schemas = inputs.flake-schemas.exportedSchemas // self.exportedSchemas;
}

To update your flake input:

nix flake update flake-schemas

In the future 1.0 release of flake-schemas, we intend to make exportedSchemas required rather than optional. When that happens, the schemas output will no longer contain schemas like devShells and packages; you’ll need to use exportedSchemas for those instead. That day hasn’t yet arrived, but we wanted to provide ample forewarning.

Feel free to reach out to us on Discord if you have any questions or run into any issues.