Flake schemas

[!NOTE] Flake schemas are currently available only in Determinate Nix. For a broad overview, check out the announcement post on the Determinate Systems blog.

This Nix flake provides a set of schema definitions for commonly used flake output types. Determinate Nix uses these schemas by default for flakes that do not have their own schemas output.

Schemas determine what is shown when you run commands like nix flake show.

Provided schemas

The schemas in this repo currently cover these output types:

• apps
• bundlers
• checks
• darwinConfigurations
• darwinModules
• devShells
• exportedSchemas (for schemas that you intend to share with the flake ecosystem)
• formatter
• homeConfigurations
• homeModules
• hydraJobs
• legacyPackages
• nixosConfigurations
• nixosModules
• ociImages
• overlays
• packages
• schemas (for use by Nix itself to understand your flake outputs)
• templates

To see an example of a flake that uses a custom schema, run this command (with Determinate Nix):

nix flake show --all-systems github:DeterminateSystems/nixos-amis

You'll notice that there's a diskImages output:

├───diskImages
│   ├───aarch64-linux
│   │   └───aws: Disk image
│   └───x86_64-linux
│       └───aws: Disk image

This output is available because the flake provides a dedicated schema for diskImages.

Using flake schemas

If a given flake has no schemas output, Determinate Nix uses the schemas in this repo as its defaults. That means that any outputs that conform to the schemas provided here are covered (devShells, packages, check, etc.).

If a given flake does have a schemas output, Determinate Nix uses that to determine the structure of the flake's outputs. What that means is that if you want non-default schemas—schemas that aren't built into Determinate Nix—you need to declare your own schemas output. Here's an example of a flake that extends the schemas in this repo:

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

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

      # other outputs
    };
}

You can extend that with one of your own custom schemas, for example:

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

  exportedSchemas.myOutputs = {
    version = 1;
    doc = "The `myOutputs` flake output.";
    inventory = output: {
      children = builtins.mapAttrs (system: value: {
        forSystems = [ system ];
        what = "my output";
      }) output;
    };
  };
}

Or you can extend with schemas from some other flake:

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

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

      # other outputs
    };
}

You can also define schemas without involving the schemas in this repo:

{
  inputs.other-flake.url = "https://flakehub.com/f/other-org/other-flake/0.1";

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

      # other outputs
    };
}

But be aware that when you do that, common schemas like devShells, packages, and others aren't available; those always need to be drawn from the default schemas in this repo.

Development

If you're interested in developing the schemas in this repo, be sure to run the tests after making any changes:

nix flake check -L ./tests

To format the Nix files in this repo, run this:

nix develop ./tests -c treefmt