E.g.

{
  options.foo = mkOption {
    type = submodule {
      # This module is in `getSubOptions` _and_ `valueMeta.configuration`
    };
  };
  config.foo = {
    # This module is only in `valueMeta.configuration`, not `getSubOptions`
  };
}

I feel like there's a subtle confusion going on here with what we mean by "definition".

A submodule is just another configuration, within a wider configuration, evaluated mostly in isolation.

Both the outer and sub configurations have modules, and those modules can contain config definitions for their respective configurations.

When I say valueMeta.configuration considers modules from config definitions, I mean config definitions in the outer configuration; definitions that define modules for the submodule to evaluate.

I feel like there's a subtle confusion going on here with what we mean by "definition".

A submodule is just another configuration, within a wider configuration, evaluated mostly in isolation.

The submodule type merges to its configuration's config value, and the configuration as a whole is exposed through valueMeta, which comes from v2 check+merge.

Both the outer and sub configurations have modules, and those modules can contain config definitions for their respective configurations.

When I say valueMeta considers modules from config definitions, I mean config definitions in the outer configuration; definitions that define modules for the submodule to evaluate.

To oversimplify, a submodule-type's lifecycle is:

1. the type is instantiated, with initial modules
   • options declared and defaults defined are visible to type.getSubOptions
2. an option is declared (in a host configuration) using the type
3. the option is defined (either via config or default, in the host configuration)
   • these definitions are modules
4. the option is merged, using the type's merge function
   1. it extends its base configuration with the defined modules
   2. it exposes the final configuration via valueMeta = { inherit configuration; }
   3. it evaluates the final value as configuration.config

For the purposes of discovering declared options, type.getSubOptions is usually suitable.

When defining a submodule (with a module), that module can declare additional options for use within the submodule. However, if you only care about options declared by modules available when the type was instantiated, then opt.type.getSubOptions opt.loc is perfectly valid.

For the purposes of discovering declared options, type.getSubOptions is usually "good enough".

When defining a submodule (with a module), that module can declare additional options for use within the submodule. However, if you only care about options declared by modules available when the type was instantiated, then opt.type.getSubOptions opt.loc is perfectly valid.

You may find it easier to actually leverage the doc's tooling and use lib.options.optionAttrSetToDocList to recursively collect a list of declared options:

$ nix repl
Nix 2.34.7
Type :? for help.

nix-repl> lib = import ./lib

nix-repl> :a import ./nixos { configuration = {}; }
Added 6 variables.
config, options, pkgs, system, vm, vmWithBootLoader

nix-repl> :p builtins.head (lib.options.optionAttrSetToDocList options)
{
  declarations = [ "lib/modules.nix" ];
  default = {
    _type = "literalExpression";
    text = "{ }";
  };
  description = <omitted for brevity>;
  internal = false;
  loc = [
    "_module"
    "args"
  ];
  name = "_module.args";
  readOnly = false;
  type = "lazy attribute set of raw value";
  visible = true;
}

The core of optionAttrsetToDocList that you can take inspiration from is:

concatMap (opt: [opt] ++ opt.type.getSubOptions opt.loc) (collect isOption options)

There are some additional option-visibility checks, partly to avoid infinite tree-recursion, partly to respect docs-visibility.

While getSubOptions is primarily intended for docs-generation, and optionAttrsetToDocList is explicitly for docs generation, you can still use getSubOptions and a similar recursive option collection pattern provided you're aware of the limitations of getSubOptions we discussed before (base-configuration from type instantiation vs final-merged configuration from valueMeta).

The options returned by getSubOptions are complete options, with full type access. It essentially just returns baseConfiguration.options (extended only to add the prefix to option loc paths).

What do you need to know about freeformType? Note that types.submodule makes it available as type.nestedTypes.freeformType (here). You're still relying on wrapper types to propagate their wrapped-types' nestedTypes though.

Luckily, freeformType is actually just the _module.freeformType option, so you can also read it from options._module.freeformType.value, which is available from getSubOptions if it was defined at type-instantiation time:

nix-repl> opt = options.services.pixelfed.nginx

nix-repl> opts = opt.type.getSubOptions opt.loc

nix-repl> opts._module.freeformType.value
null