Are there any good writeups on using lib.types?

I've gone through the manual, the nix.dev deep dive, and a bunch of other Nix module related posts, but nothing seems to cover the more advanced use cases of lib.types and submodules.

I have an option whose default depends on a value defined in the config.

options.shb.restic.databases = mkOption {
  type = attrsOf (submodule ({ name, config, ... }: {
    result = mkOption { type = submodule { options = {
      default = {
        restoreScript = config.settings.repository;
      };
    };};};
  };
};

(I'm skipping a few details in the type here, not sure what is important or not).
Everything works well AFAICT (at least the NixOS tests work fine) until I try to build the documentation of my project. And then I get:

The option `shb.restic.databases.<name>.settings' was accessed but has no value defined. Try setting the option.

Here is where the documentation code is evaluating the modules.

So I tried changing the default to use options instead of config like so: restoreScript = options.settings.value.repository;. The NixOS tests still work fine but I get the same error as above.

I also tried adding a dummy module inside the individualModuleOptionsDocs call that does something like so:

{
  config = {
    shb.restic.databases."<name>".settings = {
      repository = "...";
    };
  };
}

But that's not working either 😅 What's working is if I use a hardcoded string for the default value of the options.

Here is the PR introducing the changes leading to that error. This Github action shows the error. More specifically, here's the type definition and default setting that causes an issue.
Any idea what I should do to keep this computed default value while being able to generate the documentation?

On a totally different topic, this PR introduces 2 contracts in the form of structural typing for backing up files and backing up databases. They are both implemented by Restic. The correct implementation of both contracts is enforced by 2 generic NixOS tests (here and here) and then the Restic implementation is verified here and here.

I have an option whose default depends on a value defined in the config.

options.shb.restic.databases = mkOption {
  type = attrsOf (submodule ({ name, config, ... }: {
    result = mkOption { type = submodule { options = {
      default = {
        restoreScript = config.settings.repository;
      };
    };};};
  };
};

(I'm skipping a few details in the type here, not sure what is important or not. There's a link to the PR with the full code further down).
Everything works well AFAICT (at least the NixOS tests work fine) until I try to build the documentation of my project. And then I get:

The option `shb.restic.databases.<name>.settings' was accessed but has no value defined. Try setting the option.

Here is where the documentation code is evaluating the modules.

So I tried changing the default to use options instead of config like so: restoreScript = options.settings.value.repository;. The NixOS tests still work fine but I get the same error as above.

I also tried adding a dummy module inside the individualModuleOptionsDocs call that does something like so:

{
  config = {
    shb.restic.databases."<name>".settings = {
      repository = "...";
    };
  };
}

But that's not working either 😅 What's working is if I use a hardcoded string for the default value of the options.

Here is the PR introducing the changes leading to that error. This Github action shows the error. More specifically, here's the type definition and default setting that causes an issue.
Any idea what I should do to keep this computed default value while being able to generate the documentation?

On a totally different topic, this PR introduces 2 contracts in the form of structural typing for backing up files and backing up databases. They are both implemented by Restic. The correct implementation of both contracts is enforced by 2 generic NixOS tests (here and here) and then the Restic implementation is verified here and here.

I have an option whose default depends on a value defined in the config.

options.shb.restic.databases = mkOption {
  type = attrsOf (submodule ({ name, config, ... }: {
    result = mkOption { type = submodule { options = {
      default = {
        restoreScript = config.settings.repository;
      };
    };};};
  };
};

(I'm skipping a few details in the type here, not sure what is important or not. There's a link to the PR with the full code further down).
Everything works well AFAICT (at least the NixOS tests work fine) until I try to build the documentation of my project. And then I get:

The option `shb.restic.databases.<name>.settings' was accessed but has no value defined. Try setting the option.

Here is where the documentation code is evaluating the modules.

So I tried changing the default to use options instead of config like so: restoreScript = options.settings.value.repository;. The NixOS tests still work fine but I get the same error as above.

I also tried adding a dummy module inside the individualModuleOptionsDocs call that does something like so:

{
  config = {
    shb.restic.databases."<name>".settings = {
      repository = "...";
    };
  };
}

But that's not working either 😅 What's working is if I use a hardcoded string for the default value of the options.

Here is the PR introducing the changes leading to that error. This Github action shows the error. More specifically, here's the type definition and default setting that causes an issue.
Any idea what I should do to keep this computed default value while being able to generate the documentation?

On a totally different topic, this PR introduces 2 contracts in the form of structural typing for backing up files and backing up databases. They are both implemented by Restic. The correct implementation of both contracts is enforced by 2 generic NixOS tests (here and here) and then the Restic implementation is verified here and here.

ibizaman: I definitely agree on the fact that we need contracts, at the very least for cases where we have multiple implementations. However, I do not know what you attempted to do with mkOption and I want to suggest a very simple idea instead: “options are already one form of contracts”, there is no need to add an additional layer on top of mkOption, and most people should never look into mkOption.

On the other hand imagine the following:

config.contracts.reverse_proxy.<name> = { … };

This could be what is targetted by requesters which are looking for having a reverse proxy.

But how does these contract get honored? We could add an enum type, where each implementation provide a new entry in the enumerated type of the contract as a provider. If the provider is selected for the given contract, then we can forward the configuration to the provider option.