# Options Types {#sec-option-types}

Option types are a way to put constraints on the values a module option
can take. Types are also responsible of how values are merged in case of
multiple value definitions.

## Basic types {#sec-option-types-basic}

Basic types are the simplest available types in the module system. Basic
types include multiple string types that mainly differ in how definition
merging is handled.

`types.bool`

:   A boolean, its values can be `true` or `false`.
    All definitions must have the same value, after priorities. An error is thrown in case of a conflict.

`types.boolByOr`

:   A boolean, its values can be `true` or `false`.
    The result is `true` if _any_ of multiple definitions is `true`.
    In other words, definitions are merged with the logical _OR_ operator.

`types.path`

:   A filesystem path that starts with a slash. Even if derivations can be
     considered as paths, the more specific `types.package` should be preferred.

`types.pathInStore`

:   A path that is contained in the Nix store. This can be a top-level store
    path like `pkgs.hello` or a descendant like `"${pkgs.hello}/bin/hello"`.

`types.pathWith` { *`inStore`* ? `null`, *`absolute`* ? `null` }

:   A filesystem path. Either a string or something that can be coerced
    to a string.

    **Parameters**

    `inStore` (`Boolean` or `null`, default `null`)
    : Whether the path must be in the store (`true`), must not be in the store
      (`false`), or it doesn't matter (`null`)

    `absolute` (`Boolean` or `null`, default `null`)
    : Whether the path must be absolute (`true`), must not be absolute
      (`false`), or it doesn't matter (`null`)

    **Behavior**
    - `pathWith { inStore = true; }` is equivalent to `pathInStore`
    - `pathWith { absolute = true; }` is equivalent to `path`
    - `pathWith { inStore = false; absolute = true; }` requires an absolute
      path that is not in the store. Useful for password files that shouldn't be
      leaked into the store.

`types.package`

:   A top-level store path. This can be an attribute set pointing
    to a store path, like a derivation or a flake input.

`types.enum` *`l`*

:   One element of the list *`l`*, e.g. `types.enum [ "left" "right" ]`.
    Multiple definitions cannot be merged.

    If you want to pair these values with more information, possibly of
    distinct types, consider using a [sum type](#sec-option-types-sums).

`types.anything`

:   A type that accepts any value and recursively merges attribute sets
    together. This type is recommended when the option type is unknown.

    ::: {#ex-types-anything .example}
    ### `types.anything`

    Two definitions of this type like

    ```nix
    {
      str = lib.mkDefault "foo";
      pkg.hello = pkgs.hello;
      fun.fun = x: x + 1;
    }
    ```

    ```nix
    {
      str = lib.mkIf true "bar";
      pkg.gcc = pkgs.gcc;
      fun.fun = lib.mkForce (x: x + 2);
    }
    ```

    will get merged to

    ```nix
    {
      str = "bar";
      pkg.gcc = pkgs.gcc;
      pkg.hello = pkgs.hello;
      fun.fun = x: x + 2;
    }
    ```
    :::

`types.raw`

:   A type which doesn't do any checking, merging or nested evaluation. It
    accepts a single arbitrary value that is not recursed into, making it
    useful for values coming from outside the module system, such as package
    sets or arbitrary data. Options of this type are still evaluated according
    to priorities and conditionals, so `mkForce`, `mkIf` and co. still work on
    the option value itself, but not for any value nested within it. This type
    should only be used when checking, merging and nested evaluation are not
    desirable.

`types.optionType`

:   The type of an option's type. Its merging operation ensures that nested
    options have the correct file location annotated, and that if possible,
    multiple option definitions are correctly merged together. The main use
    case is as the type of the `_module.freeformType` option.