Yes, there's a few "types" of thing in the module system:

1. configuration is the final evaluated module eval, returned by evalModules. It contains _type, options, config, type` (a submodule option-type), etc
2. module these are the "modules" the module system evaluates. Can be a long-form or short-hand attrset, a function returning one, or a file containing one.
3. options these describe the attrs that can be defined in the configuration. Declared using options.foo = mkOption {}, defined using config.foo = "value" (or the short-hand syntax foo = "value").
4. option-types these are types that options can declare they have. This is where type checking and definition merging is done.

Submodules are an option-type representing another configuration. The submodule type expects the option definitions to be modules, and it merges those modules using evalModules and uses the configuration's config as its final value.

I'm not sure. Usually merging things relates to having multiple definitions for an option, but the module system does also support merging multiple declarations for an option too, in some scenarios.

You may be able to declare options._module.freeformType = mkOption { apply = x: x; }, but IDK why you would want to do that... ?

path values only get copied to the store when used with string interpolation (e.g. "${./some/path}"). If you instead stringify them with toString, then they are not copied.

E.g.

"${./foo}"
=> "/nix/store/r1l6z113nnzx44iiqp728f50lpczp577-foo"

toString ./foo
=> "/home/matt/foo"

./foo
=> /home/matt/foo

nixos/lib/eval-config.nix
71-  pkgsModule = rec {
72:    _file = ./eval-config.nix;
73:    key = _file;

$ man configuration.nix
...
       nixpkgs.pkgs
...
           Declared by:
               <nixpkgs/nixos/modules/misc/nixpkgs.nix>

actually does pass strings around

No, but when rendering files in errors, docs, etc they are stringified using toString

For simple/flat options, all the definition listed in the option are the ones that "won" the priority.

Specifically, all of opt.definitions and opt.definitionsWithLocations have opt.highestPrio.

That's because most wrappers like mkIf, mkMerge, mkOverride, and mkOrder are resolved before creating the option's definitions list.

However, this is only done for the option's definitions (i.e. the top-level). Wrappers on nested attrs are applied by the option's type when it merges the option's definitions.

I don't know of an "easy" way to filter for definitions of a specific attr on an attrsOf type.

There are some functions like lib.modules.mergeAttrDefinitionsWithPrio, so maybe something similar exists or could be written that exposes definition location for attrsOf sub-attrs?

If you were dealing with a submodule, and had an explicit suboption declared, then you could access the suboption's definitions within the submodule eval. E.g., you could expose them to the wider module eval by defining an internal option in the submodule.

I'm trying to create a settings option for services.dovecot2 (https://github.com/NixOS/nixpkgs/pull/388463/) and running into some issues trying to use a submodule for the type of the settings option.

Dovecot allows you to do something like this:

# dovecot config format:
service imap-login {
  restart_request_count = 1
  inet_listener imaps {
    port = 993
    ssl = yes
  }
}

# Nix:
"service imap-login" = {
  restart_request_count = 1;
  "inet_listener imaps" = {
    port = 993;
    ssl = true;
  };
};

Technically the following works for options.settings.type:

type =
  let
    inherit (lib.types) bool int listOf nullOr oneOf str submodule;
    inherit (lib) elemAt singleton split;
    any = oneOf [ int str bool (lib.types.lazyAttrsOf configValueType) ];
    configValueType = nullOr (oneOf [
      any
      (listOf any)
    ]);
  in
  configValueType;

But a better solution would be to define the section type & section name (e.g. service & imap-login or inet_listener & imaps from above) in the options part of a submodule instead of hiding it in the parser that writes the config file:

type =
  let
    inherit (lib.types) attrsOf bool int listOf nullOr oneOf str submodule;
    inherit (lib) elemAt singleton split;
    section = submodule (
      { name, config, ... }:
      let
        # split on first space
        splits = elemAt (elemAt (split "^([^ ]+)( +(.+))?$" name) 1);
        typeDefault = splits 0;
        nameDefault = splits 1; # 2;
      in
      {
        options = {
          section = {
            type = mkOption {
              description = "...";
              type = str;
              default = typeDefault;
            };
            name = mkOption {
              description = "...";
              type = nullOr str;
              default = nameDefault;
            };
          };
        };
        freeformType = configValueType;
      }
    );
    any = oneOf [ int str bool (lib.types.lazyAttrsOf section) ];
    configValueType = nullOr (oneOf [
      any
      (listOf any)
    ]);
  in
  configValueType;

However this throws and then infrecs trying to evaluate description:

       … from call site
         at /nix/store/iarry5sq6zg1wm91f4dn68a91nqs369w-source/nixos/modules/services/mail/dovecot.nix:794:65:
          793|       }
          794|       // optionalAttrs (cfg.settings ? mail_uid && cfg.settings.mail_uid != null && cfg.createMailUser) {
             |                                                                 ^
          795|         ${cfg.settings.mail_uid} =

       … while calling anonymous lambda
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:818:27:
          817|                   (
          818|                     name: defs:
             |                           ^
          819|                     let

       … while evaluating the attribute 'optionalValue.value'
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/modules.nix:1148:41:
         1147|
         1148|     optionalValue = if isDefined then { value = mergedValue; } else { };
             |                                         ^
         1149|   };

       … while calling the 'throw' builtin
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/modules.nix:1139:11:
         1138|           in
         1139|           throw "A definition for option `${showOption loc}' is not of type `${type.description}'. Definition values:${showDefs allInvalid}"
             |           ^
         1140|       else

       … while evaluating the attribute 'description'
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:266:9:
          265|             functor;
          266|         description = if description == null then name else description;
             |         ^
          267|       };

       … while evaluating description
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:266:26:
          265|             functor;
          266|         description = if description == null then name else description;
             |                          ^
          267|       };

       … while evaluating the attribute '_module.freeformType.description'
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:266:9:
          265|             functor;
          266|         description = if description == null then name else description;
             |         ^
          267|       };

       … while evaluating description
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:266:26:
          265|             functor;
          266|         description = if description == null then name else description;
             |                          ^
          267|       };

       … from call site
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:1026:13:
         1025|           description = "null or ${
         1026|             optionDescriptionPhrase (class: class == "noun" || class == "conjunction") elemType
             |             ^
         1027|           }";

       … while calling 'optionDescriptionPhrase'
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:290:23:
          289|     optionDescriptionPhrase =
          290|       unparenthesize: t:
             |                       ^
          291|       if unparenthesize (t.descriptionClass or null) then t.description else "(${t.description})";

       … while evaluating the attribute 'description'
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:266:9:
          265|             functor;
          266|         description = if description == null then name else description;
             |         ^
          267|       };

       … while evaluating description
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:266:26:
          265|             functor;
          266|         description = if description == null then name else description;
             |                          ^
          267|       };

       … from call site
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:1383:18:
         1382|             else
         1383|               "${optionDescriptionPhrase (class: class == "noun" || class == "conjunction") t1} or ${
             |                  ^
         1384|                 optionDescriptionPhrase (

       … while calling 'optionDescriptionPhrase'
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:290:23:
          289|     optionDescriptionPhrase =
          290|       unparenthesize: t:
             |                       ^
          291|       if unparenthesize (t.descriptionClass or null) then t.description else "(${t.description})";

       … while evaluating the attribute 'description'
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:266:9:
          265|             functor;
          266|         description = if description == null then name else description;
             |         ^
          267|       };

       … while evaluating description
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:266:26:
          265|             functor;
          266|         description = if description == null then name else description;
             |                          ^
          267|       };

       … from call site
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:1384:17:
         1383|               "${optionDescriptionPhrase (class: class == "noun" || class == "conjunction") t1} or ${
         1384|                 optionDescriptionPhrase (
             |                 ^
         1385|                   class: class == "noun" || class == "conjunction" || class == "composite"

       … while calling 'optionDescriptionPhrase'
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:290:23:
          289|     optionDescriptionPhrase =
          290|       unparenthesize: t:
             |                       ^
          291|       if unparenthesize (t.descriptionClass or null) then t.description else "(${t.description})";

       … while evaluating the attribute 'description'
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:266:9:
          265|             functor;
          266|         description = if description == null then name else description;
             |         ^
          267|       };

       … while evaluating description
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:266:26:
          265|             functor;
          266|         description = if description == null then name else description;
             |                          ^
          267|       };

       … from call site
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:808:22:
          807|             (if lazy then "lazy attribute set" else "attribute set")
          808|             + " of ${optionDescriptionPhrase (class: class == "noun" || class == "composite") elemType}";
             |                      ^
          809|           descriptionClass = "composite";

       … while calling 'optionDescriptionPhrase'
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:290:23:
          289|     optionDescriptionPhrase =
          290|       unparenthesize: t:
             |                       ^
          291|       if unparenthesize (t.descriptionClass or null) then t.description else "(${t.description})";

       … while evaluating the attribute 'description'
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:266:9:
          265|             functor;
          266|         description = if description == null then name else description;
             |         ^
          267|       };

       error: infinite recursion encountered
       at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:266:9:
          265|             functor;
          266|         description = if description == null then name else description;
             |         ^
          267|       };

Is what I'm trying to do here not possible with submodules due to the recursion or am I missing something?

I'm trying to create a settings option for services.dovecot2 (https://github.com/NixOS/nixpkgs/pull/388463/) and running into some issues trying to use a submodule for the type of the settings option.

Dovecot allows you to do something like this:

# dovecot config format:
service imap-login {
  restart_request_count = 1
  inet_listener imaps {
    port = 993
    ssl = yes
  }
}

# Nix:
"service imap-login" = {
  restart_request_count = 1;
  "inet_listener imaps" = {
    port = 993;
    ssl = true;
  };
};

Technically the following works for options.settings.type:

type =
  let
    inherit (lib.types) bool int listOf nullOr oneOf str submodule;
    inherit (lib) elemAt singleton split;
    any = oneOf [ int str bool (lib.types.lazyAttrsOf configValueType) ];
    configValueType = nullOr (oneOf [
      any
      (listOf any)
    ]);
  in
  configValueType;

But a better solution would be to define the section type & section name (e.g. service & imap-login or inet_listener & imaps from above) in the options part of a submodule instead of hiding it in the parser that writes the config file:

type =
  let
    inherit (lib.types) attrsOf bool int listOf nullOr oneOf str submodule;
    inherit (lib) elemAt singleton split;
    section = submodule (
      { name, config, ... }:
      let
        # split on first space
        splits = elemAt (elemAt (split "^([^ ]+)( +(.+))?$" name) 1);
        typeDefault = splits 0;
        nameDefault = splits 1;
      in
      {
        options = {
          section = {
            type = mkOption {
              description = "...";
              type = str;
              default = typeDefault;
            };
            name = mkOption {
              description = "...";
              type = nullOr str;
              default = nameDefault;
            };
          };
        };
        freeformType = configValueType;
      }
    );
    any = oneOf [ int str bool (lib.types.lazyAttrsOf section) ];
    configValueType = nullOr (oneOf [
      any
      (listOf any)
    ]);
  in
  configValueType;

However this throws and then infrecs trying to evaluate description:

       … from call site
         at /nix/store/iarry5sq6zg1wm91f4dn68a91nqs369w-source/nixos/modules/services/mail/dovecot.nix:794:65:
          793|       }
          794|       // optionalAttrs (cfg.settings ? mail_uid && cfg.settings.mail_uid != null && cfg.createMailUser) {
             |                                                                 ^
          795|         ${cfg.settings.mail_uid} =

       … while calling anonymous lambda
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:818:27:
          817|                   (
          818|                     name: defs:
             |                           ^
          819|                     let

       … while evaluating the attribute 'optionalValue.value'
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/modules.nix:1148:41:
         1147|
         1148|     optionalValue = if isDefined then { value = mergedValue; } else { };
             |                                         ^
         1149|   };

       … while calling the 'throw' builtin
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/modules.nix:1139:11:
         1138|           in
         1139|           throw "A definition for option `${showOption loc}' is not of type `${type.description}'. Definition values:${showDefs allInvalid}"
             |           ^
         1140|       else

       … while evaluating the attribute 'description'
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:266:9:
          265|             functor;
          266|         description = if description == null then name else description;
             |         ^
          267|       };

       … while evaluating description
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:266:26:
          265|             functor;
          266|         description = if description == null then name else description;
             |                          ^
          267|       };

       … while evaluating the attribute '_module.freeformType.description'
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:266:9:
          265|             functor;
          266|         description = if description == null then name else description;
             |         ^
          267|       };

       … while evaluating description
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:266:26:
          265|             functor;
          266|         description = if description == null then name else description;
             |                          ^
          267|       };

       … from call site
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:1026:13:
         1025|           description = "null or ${
         1026|             optionDescriptionPhrase (class: class == "noun" || class == "conjunction") elemType
             |             ^
         1027|           }";

       … while calling 'optionDescriptionPhrase'
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:290:23:
          289|     optionDescriptionPhrase =
          290|       unparenthesize: t:
             |                       ^
          291|       if unparenthesize (t.descriptionClass or null) then t.description else "(${t.description})";

       … while evaluating the attribute 'description'
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:266:9:
          265|             functor;
          266|         description = if description == null then name else description;
             |         ^
          267|       };

       … while evaluating description
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:266:26:
          265|             functor;
          266|         description = if description == null then name else description;
             |                          ^
          267|       };

       … from call site
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:1383:18:
         1382|             else
         1383|               "${optionDescriptionPhrase (class: class == "noun" || class == "conjunction") t1} or ${
             |                  ^
         1384|                 optionDescriptionPhrase (

       … while calling 'optionDescriptionPhrase'
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:290:23:
          289|     optionDescriptionPhrase =
          290|       unparenthesize: t:
             |                       ^
          291|       if unparenthesize (t.descriptionClass or null) then t.description else "(${t.description})";

       … while evaluating the attribute 'description'
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:266:9:
          265|             functor;
          266|         description = if description == null then name else description;
             |         ^
          267|       };

       … while evaluating description
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:266:26:
          265|             functor;
          266|         description = if description == null then name else description;
             |                          ^
          267|       };

       … from call site
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:1384:17:
         1383|               "${optionDescriptionPhrase (class: class == "noun" || class == "conjunction") t1} or ${
         1384|                 optionDescriptionPhrase (
             |                 ^
         1385|                   class: class == "noun" || class == "conjunction" || class == "composite"

       … while calling 'optionDescriptionPhrase'
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:290:23:
          289|     optionDescriptionPhrase =
          290|       unparenthesize: t:
             |                       ^
          291|       if unparenthesize (t.descriptionClass or null) then t.description else "(${t.description})";

       … while evaluating the attribute 'description'
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:266:9:
          265|             functor;
          266|         description = if description == null then name else description;
             |         ^
          267|       };

       … while evaluating description
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:266:26:
          265|             functor;
          266|         description = if description == null then name else description;
             |                          ^
          267|       };

       … from call site
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:808:22:
          807|             (if lazy then "lazy attribute set" else "attribute set")
          808|             + " of ${optionDescriptionPhrase (class: class == "noun" || class == "composite") elemType}";
             |                      ^
          809|           descriptionClass = "composite";

       … while calling 'optionDescriptionPhrase'
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:290:23:
          289|     optionDescriptionPhrase =
          290|       unparenthesize: t:
             |                       ^
          291|       if unparenthesize (t.descriptionClass or null) then t.description else "(${t.description})";

       … while evaluating the attribute 'description'
         at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:266:9:
          265|             functor;
          266|         description = if description == null then name else description;
             |         ^
          267|       };

       error: infinite recursion encountered
       at /nix/store/p893dkrzm5rxvhnqh092prgi1a7dzmcy-source/lib/types.nix:266:9:
          265|             functor;
          266|         description = if description == null then name else description;
             |         ^
          267|       };

Is what I'm trying to do here not possible with submodules due to the recursion or am I missing something?

lazyAttrsOf

Slightly off topic, but this probably isn't what you want in a freeform settings type; if a use does settings.foo = mkIf false {}, then foo will be defined, but as an "empty value" stub; usually an empty value is a throw expression throwing something like "option settings.foo is used but not defined". This will be a problem when you later want to serialize settings into the program's config format.

lazyAttrsOf

Slightly off topic, but this probably isn't what you want in a freeform settings type; if a user defines settings.foo = mkIf false {}, then foo will be defined, but as an "empty value" stub; usually an empty value is a throw expression throwing something like "option settings.foo is used but not defined". This will be a problem when you later want to serialize settings into the program's config format.

However this throws and then infrecs trying to evaluate description:

Typically, these RFC42-style types define their own description. Looking in pkgs/pkgs-lib/formats.nix you'll see descriptions like "TOML value", "Lua value", "JSON value", etc.

section submodule of { type :: string, name :: string, ... :: configValueType }

It's neat how it auto-splits the attrname into type and name options, however one concern I have with your "section" type is naming conflicts. E.g. what would happen if the section needed to define actual config with the key "name" or "type"?

There aren't many good solutions to this, and we have a similar issue with libconfuse sections in #401565. In fact, this program may even be using a libconfuse-compatible config format, so perhaps we can collaborate on a solution there?

One solution may be to _prefix these options? this would indicate they are "internal" to the nix type, and should reduce the chance of naming conflicts.

Incidentally, libconfuse calls these elements "section name" and "section title" respectively. Libconfuse is further complicated by also supporting sections that don't take a "title", so we'd need to decide how to represent that. With your design, it could be that the title option is nullable.

# split on first space
splits = elemAt (elemAt (split "^([^ ]+)( +(.+))?$" name) 1);
typeDefault = splits 0;
nameDefault = splits 1;

Personally I would match this with regex groups instead of trying to use split. The trouble with split is that it'll split an arbitrary number of times.

splits = builtins.match "([^ ]+) (.+)" name;
typeDefault = if splits == null then name else builtins.elemAt splits 0; # aka libconfuse "name"
nameDefault = if splits == null then null else builtins.elemAt splits 1;   # aka libconfuse "title"

However this throws and then infrecs trying to evaluate description:

Typically, these RFC42-style types define their own description. Looking in pkgs/pkgs-lib/formats.nix you'll see descriptions like "TOML value", "Lua value", "JSON value", etc.

Specifying an explicit description should avoid the inf-rec:

in
configValueType // {
  description = "TODO: write desc";
};