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

where in the functor payloads the information can be found

the final merged configuration isn't visible to the functor. Because it only exists after merging option definitions. Option definitions can only exist once a type is used with an option.

where in the functor payloads the information can be found

the final merged configuration isn't visible to the functor. Because it only exists after merging option definitions. Option definitions can only exist once a type is used with an option.
So if you must do this from the type's perspective, the base-configuration (pre option-merge) is all you have access to.

The functor you referred to is options.services.<module>.type.functor, right? Note that you've stepped from the option (options.services.<module>) into its type .type. The type's functor is defined when the type is created, before any options are in the picture.

The option itself has access to it's final merged value (options.services.<module>.value) and if its type supports v2 check+merge, you may also have merged metadata (options.services.<module>.valueMeta). Note how none of that is under .type.

Once you return options.services.<module>.type.getSubOptions options.services.<module>.loc you have a new set of options that came from the type's base configuration; you've lost all knowledge of the owner option, its definitions, merged value, or merged metadata.

I always recommend trying to keep the prefix accurate, so that once you have your final list of options you can do "${opt}" or showOption opt.loc and get the correct option attrpath. But you're right, functionally it makes no difference.
Having correct locs can be useful in attrsOf submodule scenarios, too, where we typically add "<name>" to the prefix. Or listOf submodule where we add "*" to the prefix.

In my interpretation of getSubOptions, it makes no guarantee of its structure. Imagine a type like either or attrTag, where different submodules could in theory be supported. It may make sense for such a type's getSubOptions to return an attrset of wrapped-type-name -> sub-options to avoid naming conflicts.

I'm not aware of any types that do that currently, but it's something to be aware of.

I always recommend trying to keep the prefix accurate, so that once you have your final list of options you can do "${opt}" or showOption opt.loc and get the correct option attrpath. But you're right, functionally it makes no difference.
Having correct locs can be useful in attrsOf submodule scenarios, too, where we typically add "<name>" to the prefix. Or listOf submodule where we add "*" to the prefix.

This may be controversial, but in my interpretation of getSubOptions, it makes no guarantee of its structure. Imagine a type like either or attrTag, where different submodules could in theory be supported. It may make sense for such a type's getSubOptions to return an attrset of wrapped-type-name -> sub-options to avoid naming conflicts.

I'm not aware of any types that do that currently, but it's something to be aware of.

Yeah. Although currently that's not very common because it's not easy to discriminate between submodule-specific module definitions. A more practical example may be

either (attrsOf submoduleA) (listOf submoduleB)