My MRE attempt is producing the expected behavior:

nix-repl> (lib.modules.mergeDefinitions [] result.list-type' [ { file = "."; value = ["a"]; } { file = "."; value = ["b"]; } ]).mergedValue
[ "a'" "b'" ]

nix-repl> (lib.modules.mergeDefinitions [] result.configuration.options.list'.type [ { file = "."; value = ["a"]; } { file = "."; value = ["b"]; } ]).mergedValue
[ "a'" "b'" ]

nix-repl> (lib.modules.mergeDefinitions [] result.attrs-type' [ { file = "."; value = { a = "a"; }; } { file = "."; value = { b = "b"; }; } ]).mergedValue
{ a = "a'"; b = "b'"; }

nix-repl> (lib.modules.mergeDefinitions [] result.configuration.options.attrs'.type [ { file = "."; value = { a = "a"; }; } { file = "."; value = { b = "b"; }; } ]).mergedValue
{ a = "a'"; b = "b'"; }

So I'm struggling to understand why in #2342 I have issues where the the type behaves differently after being used in evalModules and/or listOf:

nix-repl> (lib.modules.mergeDefinitions [] lib.nixvim.keymaps.deprecatedMapOptionSubmodule  [ { file = "."; value = {key = "a"; action = "b";}; } ]).mergedValue
{ action = "b"; key = "a"; mode = ""; options = { ... }; }

nix-repl> (lib.modules.mergeDefinitions [] legacyPackages.x86_64-linux.nixvimConfiguration.options.keymaps.type.nestedTypes.elemType  [ { file = "."; value ={ action = "b"; key = "a"; lua = «error: error:
       … while evaluating the attribute 'value'

         at /nix/store/fpivx4sjcp2vk4rp9nhliln5cwcp3kc6-source/lib/modules.nix:821:9:

          820|     in warnDeprecation opt //
          821|       { value = addErrorContext "while evaluating the option `${showOption loc}':" value;
             |         ^
          822|         inherit (res.defsFinal') highestPrio;

       … while calling the 'addErrorContext' builtin

         at /nix/store/fpivx4sjcp2vk4rp9nhliln5cwcp3kc6-source/lib/modules.nix:821:17:

          820|     in warnDeprecation opt //
          821|       { value = addErrorContext "while evaluating the option `${showOption loc}':" value;
             |                 ^
          822|         inherit (res.defsFinal') highestPrio;

       (stack trace truncated; use '--show-trace' to show the full trace)

       error: The option `lua' was accessed but has no value defined. Try setting the option.»; mode = ""; options = { ... }; }

nix-repl> builtins.head (lib.modules.mergeDefinitions [] legacyPackages.x86_64-linux.nixvimConfiguration.options.keymaps.type  [ { file = "."; value = [{key = "a"; action = "b";}]; } { file = "."; value = [{ key = "c"; action = "d";}]; } ]).mergedValue
{ action = "b"; key = "a"; lua = «error: error:
       … while evaluating the attribute 'value'

         at /nix/store/fpivx4sjcp2vk4rp9nhliln5cwcp3kc6-source/lib/modules.nix:821:9:

          820|     in warnDeprecation opt //
          821|       { value = addErrorContext "while evaluating the option `${showOption loc}':" value;
             |         ^
          822|         inherit (res.defsFinal') highestPrio;

       … while calling the 'addErrorContext' builtin

         at /nix/store/fpivx4sjcp2vk4rp9nhliln5cwcp3kc6-source/lib/modules.nix:821:17:

          820|     in warnDeprecation opt //
          821|       { value = addErrorContext "while evaluating the option `${showOption loc}':" value;
             |                 ^
          822|         inherit (res.defsFinal') highestPrio;

       (stack trace truncated; use '--show-trace' to show the full trace)

       error: The option `"[definition 1-entry 1]".lua' was accessed but has no value defined. Try setting the option.»; mode = ""; options = { ... }; }

NOTE: legacyPackages.x86_64-linux.nixvimConfiguration.options.keymaps.type.nestedTypes.elemType and lib.nixvim.keymaps.deprecatedMapOptionSubmodule should be the same thing, but one works correctly while the other does not.

The keymaps option is literally defined as:

keymaps = lib.mkOption {
  type = lib.types.listOf helpers.keymaps.deprecatedMapOptionSubmodule;
  # ...
}

EDIT: Accessing lib via special args also does not produce the issue (i.e. works correctly):

nix-repl> (lib.modules.mergeDefinitions [] legacyPackages.x86_64-linux.nixvimConfiguration._module.specialArgs.lib.nixvim.keymaps.deprecatedMapOptionSubmodule  [ { file = "."; value = {key = "a"; action = "b";}; } ]).mergedValue
{ action = "b"; key = "a"; mode = ""; options = { ... }; }

My MRE attempt is producing the expected behavior:

nix-repl> (lib.modules.mergeDefinitions [] result.list-type' [ { file = "."; value = ["a"]; } { file = "."; value = ["b"]; } ]).mergedValue
[ "a'" "b'" ]

nix-repl> (lib.modules.mergeDefinitions [] result.configuration.options.list'.type [ { file = "."; value = ["a"]; } { file = "."; value = ["b"]; } ]).mergedValue
[ "a'" "b'" ]

nix-repl> (lib.modules.mergeDefinitions [] result.attrs-type' [ { file = "."; value = { a = "a"; }; } { file = "."; value = { b = "b"; }; } ]).mergedValue
{ a = "a'"; b = "b'"; }

nix-repl> (lib.modules.mergeDefinitions [] result.configuration.options.attrs'.type [ { file = "."; value = { a = "a"; }; } { file = "."; value = { b = "b"; }; } ]).mergedValue
{ a = "a'"; b = "b'"; }

So I'm struggling to understand why in #2342 I have issues where the the type behaves differently after being used in evalModules and/or listOf:

nix-repl> (lib.modules.mergeDefinitions [] lib.nixvim.keymaps.deprecatedMapOptionSubmodule  [ { file = "."; value = {key = "a"; action = "b";}; } ]).mergedValue
{ action = "b"; key = "a"; mode = ""; options = { ... }; }

nix-repl> (lib.modules.mergeDefinitions [] legacyPackages.x86_64-linux.nixvimConfiguration.options.keymaps.type.nestedTypes.elemType  [ { file = "."; value ={ action = "b"; key = "a"; lua = «error: error:
       … while evaluating the attribute 'value'

         at /nix/store/fpivx4sjcp2vk4rp9nhliln5cwcp3kc6-source/lib/modules.nix:821:9:

          820|     in warnDeprecation opt //
          821|       { value = addErrorContext "while evaluating the option `${showOption loc}':" value;
             |         ^
          822|         inherit (res.defsFinal') highestPrio;

       … while calling the 'addErrorContext' builtin

         at /nix/store/fpivx4sjcp2vk4rp9nhliln5cwcp3kc6-source/lib/modules.nix:821:17:

          820|     in warnDeprecation opt //
          821|       { value = addErrorContext "while evaluating the option `${showOption loc}':" value;
             |                 ^
          822|         inherit (res.defsFinal') highestPrio;

       (stack trace truncated; use '--show-trace' to show the full trace)

       error: The option `lua' was accessed but has no value defined. Try setting the option.»; mode = ""; options = { ... }; }

nix-repl> builtins.head (lib.modules.mergeDefinitions [] legacyPackages.x86_64-linux.nixvimConfiguration.options.keymaps.type  [ { file = "."; value = [{key = "a"; action = "b";}]; } { file = "."; value = [{ key = "c"; action = "d";}]; } ]).mergedValue
{ action = "b"; key = "a"; lua = «error: error:
       … while evaluating the attribute 'value'

         at /nix/store/fpivx4sjcp2vk4rp9nhliln5cwcp3kc6-source/lib/modules.nix:821:9:

          820|     in warnDeprecation opt //
          821|       { value = addErrorContext "while evaluating the option `${showOption loc}':" value;
             |         ^
          822|         inherit (res.defsFinal') highestPrio;

       … while calling the 'addErrorContext' builtin

         at /nix/store/fpivx4sjcp2vk4rp9nhliln5cwcp3kc6-source/lib/modules.nix:821:17:

          820|     in warnDeprecation opt //
          821|       { value = addErrorContext "while evaluating the option `${showOption loc}':" value;
             |                 ^
          822|         inherit (res.defsFinal') highestPrio;

       (stack trace truncated; use '--show-trace' to show the full trace)

       error: The option `"[definition 1-entry 1]".lua' was accessed but has no value defined. Try setting the option.»; mode = ""; options = { ... }; }

NOTE: legacyPackages.x86_64-linux.nixvimConfiguration.options.keymaps.type.nestedTypes.elemType and lib.nixvim.keymaps.deprecatedMapOptionSubmodule should be the same thing, but one works correctly while the other does not.

The keymaps option is literally defined as:

keymaps = lib.mkOption {
  type = lib.types.listOf lib.nixvim.keymaps.deprecatedMapOptionSubmodule;
  # ...
}

EDIT: Accessing lib via special args also does not produce the issue (i.e. works correctly):

nix-repl> (lib.modules.mergeDefinitions [] legacyPackages.x86_64-linux.nixvimConfiguration._module.specialArgs.lib.nixvim.keymaps.deprecatedMapOptionSubmodule  [ { file = "."; value = {key = "a"; action = "b";}; } ]).mergedValue
{ action = "b"; key = "a"; mode = ""; options = { ... }; }

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.