diff --git a/CHANGELOG.md b/CHANGELOG.md
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,39 @@
 # Changelog
 
+## [0.2.0.0] - 2026-11-14
+
+### Added
+
+* `ExprLam`, `ExprLet`, `ExprIf`, `ExprUpdate` and `ExprSelect`.
+* `optionRequirement`, `optionAlternativeDefaults` and `optionDocumentedDefault`
+  in `Option`.
+
+### Changed
+
+* A key that may be left out no longer defaults to `null`, and is left out of
+  the value when it is not set.
+* A generated submodule throws when a required key is not set.
+* The submodules of a choice between objects are merged into one.
+* Generated types need nixpkgs 25.11 or newer.
+
+### Removed
+
+* `renderNixOptionsVia`, `renderNixOptionsViaCodec`, `optionsExpression` and
+  `optionsExpr`.
+  Use `renderNixOptionTypeVia` instead.
+
+### Fixed
+
+* The discriminator of a discriminated union is an enum.
+* Strings and quoted attribute keys are rendered as Nix string literals.
+  They used to be rendered as Haskell string literals, so Nix read a
+  non-ASCII character like `é` as its code point, `233`, and interpolated a
+  `${`.
+* A negative number in a list or as an argument is put in parentheses.
+  Nix read `[ -1 ]` as a subtraction, which it could not parse.
+* The element of a list of one element is put in parentheses when it needs
+  them, so an application in it is no longer read as two elements.
+
 ## [0.1.1.0] - 2026-10-06
 
 ### Changed
diff --git a/autodocodec-nix.cabal b/autodocodec-nix.cabal
--- a/autodocodec-nix.cabal
+++ b/autodocodec-nix.cabal
@@ -5,7 +5,7 @@
 -- see: https://github.com/sol/hpack
 
 name:           autodocodec-nix
-version:        0.1.1.0
+version:        0.2.0.0
 synopsis:       Autodocodec interpreters for nix
 homepage:       https://github.com/NorfairKing/autodocodec#readme
 bug-reports:    https://github.com/NorfairKing/autodocodec/issues
diff --git a/src/Autodocodec/Nix.hs b/src/Autodocodec/Nix.hs
--- a/src/Autodocodec/Nix.hs
+++ b/src/Autodocodec/Nix.hs
@@ -3,12 +3,11 @@
 module Autodocodec.Nix
   ( -- * Producing a Nixos module type
     renderNixOptionTypeViaCodec,
-    renderNixOptionsViaCodec,
     renderNixOptionTypeVia,
-    renderNixOptionsVia,
     valueCodecNixOptionType,
     objectCodecNixOptions,
     Option (..),
+    OptionRequirement (..),
     emptyOption,
     simplifyOption,
     OptionType (..),
@@ -18,8 +17,6 @@
     withNixArgs,
     optionExpression,
     optionExpr,
-    optionsExpression,
-    optionsExpr,
     optionTypeExpression,
     optionTypeExpr,
 
diff --git a/src/Autodocodec/Nix/Expression.hs b/src/Autodocodec/Nix/Expression.hs
--- a/src/Autodocodec/Nix/Expression.hs
+++ b/src/Autodocodec/Nix/Expression.hs
@@ -39,61 +39,142 @@
   | ExprVar !Text
   | ExprAttrSet !(Map Text Expression)
   | ExprAp !Expression !Expression
-  | ExprFun ![Text] !Expression
+  | -- | A function with a set pattern: @{ a, b }: e@
+    ExprFun ![Text] !Expression
   | ExprWith !Text !Expression
+  | -- | A function with a single argument: @a: e@
+    ExprLam !Text !Expression
+  | ExprLet !(Map Text Expression) !Expression
+  | ExprIf !Expression !Expression !Expression
+  | -- | @e1 // e2@
+    ExprUpdate !Expression !Expression
+  | -- | @e.key@
+    ExprSelect !Expression !Text
   deriving (Show, Eq, Ord)
 
 -- {-# DEPRECATED renderExpr "Use renderExpression instead" #-}
 renderExpr :: Expr -> Text
 renderExpr = renderExpression
 
+-- | Where an expression is rendered.
+--
+-- A later position admits fewer expressions without parentheses, so an
+-- expression decides whether it needs them by comparing the position to the
+-- last one it can stand in.
+data Position
+  = -- | Where an expression ends, so anything can stand there.
+    -- A function, @let@, @if@ or @with@ extends as far to the right as it
+    -- can, so it needs this position.
+    PositionEnd
+  | -- | Where an expression is followed by more of the expression around it,
+    -- like the condition of an @if@.
+    PositionInner
+  | -- | The right operand of @//@, which groups to the right.
+    PositionUpdateRight
+  | -- | The left operand of @//@.
+    PositionUpdateLeft
+  | -- | The function of an application.
+    PositionApplied
+  | -- | An argument or a list element.
+    PositionArgument
+  | -- | Where an attribute is selected from.
+    PositionSelected
+  deriving (Eq, Ord)
+
 renderExpression :: Expr -> Text
-renderExpression = T.unlines . go 0
+renderExpression = T.unlines . go PositionEnd
   where
     parensWhen b ts = if b then parens ts else ts
-    go :: Int -> Expr -> [Text]
-    go d = \case
+    go :: Position -> Expr -> [Text]
+    go p = \case
       ExprNull -> ["null"]
       ExprLitBool b -> [if b then "true" else "false"]
-      ExprLitString s -> [T.pack $ show $ T.unpack s]
+      ExprLitString s -> [nixString s]
       ExprLitNumber s ->
-        [ case floatingOrInteger s of
-            Left f -> T.pack $ show (f :: Double)
-            Right i -> T.pack $ show (i :: Integer)
-        ]
+        -- Nix reads a minus in a list or an argument as subtraction.
+        parensWhen
+          (p > PositionApplied && s < 0)
+          [ case floatingOrInteger s of
+              Left f -> T.pack $ show (f :: Double)
+              Right i -> T.pack $ show (i :: Integer)
+          ]
       ExprLitList es -> case es of
         [] -> ["[]"]
-        [e] -> surround "[" "]" $ go 0 e
+        [e] -> surround "[" "]" $ go PositionArgument e
         _ ->
           -- If there is more than one list element, put them on separate lines.
-          "[" : indent (concatMap (go 11) es) ++ ["]"]
+          "[" : indent (concatMap (go PositionArgument) es) ++ ["]"]
       ExprVar s -> [s]
       ExprAttrSet m | null m -> ["{ }"]
       ExprAttrSet m ->
         -- We always put "{" and "}" on separate lines.
         "{" : indent (concatMap (uncurry goBind) (M.toList m)) ++ ["}"]
       ExprAp e1 e2 ->
-        parensWhen (d > 10) $
-          go 11 e1 `apply` go 11 e2
+        parensWhen (p > PositionApplied) $
+          go PositionApplied e1 `apply` go PositionArgument e2
       ExprFun args e ->
-        parensWhen (d > 10) $
+        parensWhen (p > PositionEnd) $
           surroundWith " " "{" "}:" [T.intercalate ", " args]
-            ++ go 0 e
+            ++ go PositionEnd e
       ExprWith t e ->
-        parensWhen (d > 10) $
-          ("with " <> t <> ";") : go 0 e
+        parensWhen (p > PositionEnd) $
+          ("with " <> t <> ";") : go PositionEnd e
+      ExprLam arg e ->
+        parensWhen (p > PositionEnd) $
+          prependWith " " (arg <> ":") (go PositionEnd e)
+      ExprLet binds e
+        | null binds -> go p e
+        | otherwise ->
+            parensWhen (p > PositionEnd) $
+              concat
+                [ ["let"],
+                  indent (concatMap (uncurry goBind) (M.toList binds)),
+                  ["in"],
+                  go PositionEnd e
+                ]
+      ExprIf c t e ->
+        parensWhen (p > PositionEnd) $
+          joinWith
+            " else "
+            ( joinWith
+                " then "
+                (prependWith " " "if" (go PositionInner c))
+                (go PositionInner t)
+            )
+            (go PositionEnd e)
+      ExprUpdate e1 e2 ->
+        parensWhen (p > PositionUpdateRight) $
+          joinWith " // " (go PositionUpdateLeft e1) (go PositionUpdateRight e2)
+      ExprSelect e key ->
+        go PositionSelected e `append` T.cons '.' (nixAttrKey key)
     goBind key e =
       prependWith " " (nixAttrKey key <> " =") $
         (`append` ";") $
-          go 0 e
+          go PositionEnd e
 
 -- | Quote an attribute key if it is not a valid Nix identifier.
 -- Valid identifiers match @[a-zA-Z_][a-zA-Z0-9_'-]*@.
 nixAttrKey :: Text -> Text
 nixAttrKey key
   | isNixIdentifier key = key
-  | otherwise = T.pack $ show $ T.unpack key
+  | otherwise = nixString key
 
+-- | A Nix string literal that Nix reads as the given text.
+--
+-- Not Haskell's 'show', because Nix has no numeric escapes, so it reads
+-- @\"\\233\"@ as @\"233\"@, and because Nix interpolates @${@.
+nixString :: Text -> Text
+nixString s =
+  let escape :: Char -> Text
+      escape = \case
+        '"' -> "\\\""
+        '\\' -> "\\\\"
+        '\n' -> "\\n"
+        '\r' -> "\\r"
+        '\t' -> "\\t"
+        c -> T.singleton c
+   in T.concat ["\"", T.replace "${" "\\${" (T.concatMap escape s), "\""]
+
 isNixIdentifier :: Text -> Bool
 isNixIdentifier t = case T.uncons t of
   Nothing -> False
@@ -121,11 +202,17 @@
       [t] -> [t <> spacer <> u]
       (t : ts') -> t : go ts'
 
+-- | Join the last line of the first with the first line of the second.
+joinWith :: Text -> [Text] -> [Text] -> [Text]
+joinWith spacer ts1 = \case
+  [] -> ts1
+  (t2 : ts2) -> appendWith spacer ts1 t2 ++ ts2
+
 apply :: [Text] -> [Text] -> [Text]
 apply ts1 ts2 = case (ts1, ts2) of
   ([t1], [t2]) -> [t1 <> " " <> t2]
   ([t1], _) -> prependWith " " t1 ts2
-  (_, [t2]) -> ts1 `append` t2
+  (_, [t2]) -> appendWith " " ts1 t2
   _ -> go ts1
     where
       go = \case
diff --git a/src/Autodocodec/Nix/Options.hs b/src/Autodocodec/Nix/Options.hs
--- a/src/Autodocodec/Nix/Options.hs
+++ b/src/Autodocodec/Nix/Options.hs
@@ -10,12 +10,11 @@
 module Autodocodec.Nix.Options
   ( -- * Producing a Nixos module type
     renderNixOptionTypeViaCodec,
-    renderNixOptionsViaCodec,
     renderNixOptionTypeVia,
-    renderNixOptionsVia,
     valueCodecNixOptionType,
     objectCodecNixOptions,
     Option (..),
+    OptionRequirement (..),
     emptyOption,
     simplifyOption,
     OptionType (..),
@@ -25,8 +24,6 @@
     withNixArgs,
     optionExpression,
     optionExpr,
-    optionsExpression,
-    optionsExpr,
     optionTypeExpression,
     optionTypeExpr,
     renderExpression,
@@ -36,10 +33,11 @@
 import Autodocodec
 import Autodocodec.Nix.Expression
 import Autodocodec.Nix.Render
-import Control.Applicative
 import Data.Aeson as JSON
 import Data.Containers.ListUtils
 import qualified Data.HashMap.Strict as HM
+import Data.List (intercalate)
+import qualified Data.Map.Merge.Strict as Merge
 import Data.Map.Strict (Map)
 import qualified Data.Map.Strict as M
 import Data.Maybe
@@ -49,20 +47,12 @@
 renderNixOptionTypeViaCodec :: forall a. (HasCodec a) => Text
 renderNixOptionTypeViaCodec = renderNixOptionTypeVia (codec @a)
 
-renderNixOptionsViaCodec :: forall a. (HasObjectCodec a) => Text
-renderNixOptionsViaCodec = renderNixOptionsVia (objectCodec @a)
-
 renderNixOptionTypeVia :: ValueCodec input output -> Text
 renderNixOptionTypeVia =
   renderOptionType
     . fromMaybe (OptionTypeSimple "lib.types.anything")
     . valueCodecNixOptionType
 
-renderNixOptionsVia :: ObjectCodec input output -> Text
-renderNixOptionsVia =
-  renderOptions
-    . objectCodecNixOptions
-
 valueCodecNixOptionType :: ValueCodec input output -> Maybe OptionType
 valueCodecNixOptionType = fmap simplifyOptionType . go
   where
@@ -93,104 +83,178 @@
       MapCodec c -> Just $ OptionTypeAttrsOf $ mTyp $ go c
       ValueCodec -> Just (OptionTypeSimple "lib.types.unspecified")
       ArrayOfCodec _ c -> Just $ OptionTypeListOf $ mTyp $ go c
-      ObjectOfCodec _ oc -> Just (OptionTypeSubmodule (objectCodecNixOptions oc))
+      ObjectOfCodec _ oc -> Just $ OptionTypeSubmodule $ objectCodecNixOptions oc
       EqCodec v c -> Just $ OptionTypeEnum [toNixExpressionVia c v]
       BimapCodec _ _ c -> go c
       EitherCodec _ c1 c2 -> Just $ OptionTypeOneOf (map mTyp [go c1, go c2])
       CommentCodec _ c -> go c
       ReferenceCodec {} -> Nothing -- TODO: let-binding?
 
--- [tag:NixOptionNullable]
--- Note about nullable options:
--- It's not technically accurate to represent optional fields as the 'null' value in Nix,
--- but Nix isn't very good at optional values at all, so we use 'null' for both
--- optional fields and nullable fields.
--- If Nix options ever figure out how to do optional fields, we'll use that
--- instead.
+-- | A key that may be left out gets an option without a default, so that
+-- leaving it out and setting it to 'null' can be told apart.
+-- The value of a generated submodule is what was defined in it, and nothing
+-- that was not.
+-- Reading it throws when a required option was not defined.
+--
+-- The option that a generated submodule is the type of cannot be declared
+-- again, because the module system would merge the declarations into a plain
+-- submodule, whose value is not what was defined.
 objectCodecNixOptions :: ObjectCodec input output -> Map Text Option
-objectCodecNixOptions = simplifyOptions . go False
-  where
-    -- The bool means 'force optional'
-    go :: Bool -> ObjectCodec input output -> Map Text Option
-    go b = \case
-      DiscriminatedUnionCodec k _ m ->
-        M.insert
-          k
-          ( Option
-              { optionType = Just $ OptionTypeOneOf $ map (OptionTypeSimple . T.pack . show) $ HM.keys m,
-                optionDescription = Nothing,
-                optionDefault = Nothing
+objectCodecNixOptions =
+  let undefaultedOption :: OptionRequirement -> ValueCodec input output -> Maybe Text -> Option
+      undefaultedOption requirement c mDesc =
+        Option
+          { optionType = valueCodecNixOptionType c,
+            optionDescription = optionDescriptionFor mDesc c,
+            optionDefault = Nothing,
+            optionAlternativeDefaults = [],
+            optionRequirement = requirement,
+            optionDocumentedDefault = Nothing
+          }
+      requiredByEither :: OptionRequirement -> OptionRequirement -> OptionRequirement
+      requiredByEither r1 r2 = case r1 of
+        OptionRequired -> OptionRequired
+        OptionOptional -> r2
+      go :: ObjectCodec input output -> Map Text Option
+      go = \case
+        DiscriminatedUnionCodec k _ m ->
+          -- Ordered by discriminator, so that the output does not depend on
+          -- the order of a HashMap.
+          let byDiscriminator = M.fromList $ HM.toList m
+           in M.insert
+                k
+                ( Option
+                    { optionType = Just $ OptionTypeEnum $ map ExprLitString $ M.keys byDiscriminator,
+                      optionDescription = Nothing,
+                      optionDefault = Nothing,
+                      optionAlternativeDefaults = [],
+                      optionRequirement = OptionRequired,
+                      optionDocumentedDefault = Nothing
+                    }
+                )
+                $ case map (go . snd) $ M.elems byDiscriminator of
+                  [] -> M.empty
+                  alternative : alternatives -> foldr mergeAlternatives alternative alternatives
+        RequiredKeyCodec key o mDesc -> M.singleton key $ undefaultedOption OptionRequired o mDesc
+        OptionalKeyCodec key o mDesc -> M.singleton key $ undefaultedOption OptionOptional o mDesc
+        OptionalKeyWithDefaultCodec key c defaultValue mDesc ->
+          M.singleton
+            key
+            Option
+              { optionType = valueCodecNixOptionType c,
+                optionDescription = optionDescriptionFor mDesc c,
+                optionDefault = Just $ toJSONVia c defaultValue,
+                optionAlternativeDefaults = [],
+                optionRequirement = OptionOptional,
+                optionDocumentedDefault = Nothing
               }
-          )
-          $ M.unionsWith
-            ( \t1 t2 ->
-                Option
-                  { optionType = Just $ OptionTypeOneOf $ map (fromMaybe (OptionTypeSimple "lib.types.anything") . optionType) [t1, t2],
-                    optionDescription = optionDescription t1 <|> optionDescription t2, -- TODO
-                    optionDefault = Nothing
+        OptionalKeyWithOmittedDefaultCodec key c defaultValue mDesc ->
+          M.singleton
+            key
+            Option
+              { optionType = valueCodecNixOptionType c,
+                optionDescription = optionDescriptionFor mDesc c,
+                optionDefault = Just $ toJSONVia c defaultValue,
+                optionAlternativeDefaults = [],
+                optionRequirement = OptionOptional,
+                optionDocumentedDefault = Nothing
+              }
+        PureCodec _ -> M.empty
+        ApCodec c1 c2 ->
+          M.unionWith
+            ( \o1 o2 ->
+                (mergeOption o1 o2)
+                  { optionRequirement = requiredByEither (optionRequirement o1) (optionRequirement o2)
                   }
             )
-          $ map (go b . snd)
-          $ HM.elems m
-      RequiredKeyCodec key o mDesc ->
-        M.singleton key $
-          Option
-            { optionType =
-                ( if b
-                    then fmap OptionTypeNullOr
-                    else id
-                )
-                  $ valueCodecNixOptionType o,
-              optionDescription = optionDescriptionFor mDesc o,
-              optionDefault =
-                if b
-                  then Just JSON.Null
-                  else Nothing -- [ref:NixOptionNullable]
-            }
-      OptionalKeyCodec key o mDesc ->
-        M.singleton key $
-          Option
-            { optionType = OptionTypeNullOr <$> valueCodecNixOptionType o,
-              optionDescription = optionDescriptionFor mDesc o,
-              optionDefault = Just JSON.Null -- [ref:NixOptionNullable]
-            }
-      OptionalKeyWithDefaultCodec key c defaultValue mDesc ->
-        M.singleton
-          key
-          Option
-            { optionType = valueCodecNixOptionType c,
-              optionDescription = optionDescriptionFor mDesc c,
-              optionDefault = Just $ toJSONVia c defaultValue
+            (go c1)
+            (go c2)
+        BimapCodec _ _ c -> go c
+        EitherCodec _ c1 c2 -> mergeAlternatives (go c1) (go c2)
+   in simplifyOptions . go
+
+-- | The options of a choice between objects.
+--
+-- A value for any one alternative is a valid value, so a key is only required
+-- when every alternative requires it, and only keeps a default when every
+-- alternative has the same one.
+-- Otherwise the defaults of the alternatives are kept for the documentation,
+-- because the codec applies the default of the alternative that it parses.
+mergeAlternatives :: Map Text Option -> Map Text Option -> Map Text Option
+mergeAlternatives =
+  let -- What the alternatives that an option comes from do when it is not
+      -- defined: apply a default, or leave it out.
+      -- An alternative that requires it does not parse without it, so it
+      -- does nothing.
+      whenUnset :: Option -> [Maybe JSON.Value]
+      whenUnset o = case optionRequirement o of
+        OptionRequired -> []
+        OptionOptional -> case optionAlternativeDefaults o of
+          [] -> [optionDefault o]
+          defaults -> defaults
+      withWhenUnset :: [Maybe JSON.Value] -> Option -> Option
+      withWhenUnset unset o = case nubOrd unset of
+        [d] ->
+          o
+            { optionDefault = d,
+              optionAlternativeDefaults = []
             }
-      OptionalKeyWithOmittedDefaultCodec key c defaultValue mDesc ->
-        M.singleton
-          key
-          Option
-            { optionType = valueCodecNixOptionType c,
-              optionDescription = optionDescriptionFor mDesc c,
-              optionDefault = Just $ toJSONVia c defaultValue
+        unset' ->
+          o
+            { optionDefault = Nothing,
+              optionAlternativeDefaults = unset'
             }
-      PureCodec _ -> M.empty
-      ApCodec c1 c2 -> M.unionWith mergeOption (go b c1) (go b c2)
-      BimapCodec _ _ c -> go b c
-      EitherCodec _ c1 c2 -> M.unionWith mergeOption (go True c1) (go True c2)
-    -- This throwing away of the description and the default is not ideal but
-    -- better than just taking the first option.
-    mergeOption :: Option -> Option -> Option
-    mergeOption o1 o2 =
-      o1
-        { optionType =
-            ( \ot1 ot2 ->
-                simplifyOptionType $
-                  OptionTypeOneOf
-                    [ ot1,
-                      ot2
-                    ]
+      -- The alternative that does not have the key leaves it out.
+      onlyInOne :: Option -> Option
+      onlyInOne o =
+        withWhenUnset (whenUnset o ++ [Nothing]) $
+          o {optionRequirement = OptionOptional}
+      requiredByBoth :: OptionRequirement -> OptionRequirement -> OptionRequirement
+      requiredByBoth r1 r2 = case r1 of
+        OptionRequired -> r2
+        OptionOptional -> OptionOptional
+   in Merge.merge
+        (Merge.mapMissing (const onlyInOne))
+        (Merge.mapMissing (const onlyInOne))
+        ( Merge.zipWithMatched
+            ( \_ o1 o2 ->
+                withWhenUnset (whenUnset o1 ++ whenUnset o2) $
+                  (mergeOption o1 o2)
+                    { optionRequirement = requiredByBoth (optionRequirement o1) (optionRequirement o2)
+                    }
             )
-              <$> optionType o1
-              <*> optionType o2
-        }
+        )
 
+-- | Two options for the same key.
+--
+-- Keeping only the first description is not ideal but better than dropping
+-- both.
+-- A default is only kept when both agree on it, because the value of the
+-- option is written out whichever alternative the rest of the value is for.
+mergeOption :: Option -> Option -> Option
+mergeOption o1 o2 =
+  o1
+    { optionDefault =
+        if optionDefault o1 == optionDefault o2
+          then optionDefault o1
+          else Nothing,
+      optionAlternativeDefaults = nubOrd (optionAlternativeDefaults o1 ++ optionAlternativeDefaults o2),
+      optionDocumentedDefault =
+        if optionDocumentedDefault o1 == optionDocumentedDefault o2
+          then optionDocumentedDefault o1
+          else Nothing,
+      optionType =
+        ( \ot1 ot2 ->
+            simplifyOptionType $
+              OptionTypeOneOf
+                [ ot1,
+                  ot2
+                ]
+        )
+          <$> optionType o1
+          <*> optionType o2
+    }
+
 -- | What an option says about itself: the field's own description, and then
 -- whatever comments the codec under it carries.
 --
@@ -230,16 +294,35 @@
 data Option = Option
   { optionType :: !(Maybe OptionType),
     optionDescription :: !(Maybe Text),
-    optionDefault :: !(Maybe JSON.Value)
+    optionDefault :: !(Maybe JSON.Value),
+    -- | What the alternatives of a choice between objects do when the option
+    -- is not defined, when they do not all do the same: apply a default
+    -- ('Just'), or leave it out ('Nothing').
+    -- The option then has no default, and its documentation lists these.
+    optionAlternativeDefaults :: ![Maybe JSON.Value],
+    optionRequirement :: !OptionRequirement,
+    -- | The default that whatever reads the value applies when the option is
+    -- left out, for an option without a default in Nix.
+    -- It is only documented, so that the value still leaves the option out.
+    optionDocumentedDefault :: !(Maybe JSON.Value)
   }
   deriving (Show, Eq, Ord)
 
+-- | Whether an option has to be defined.
+data OptionRequirement
+  = OptionRequired
+  | OptionOptional
+  deriving (Show, Eq, Ord)
+
 emptyOption :: Option
 emptyOption =
   Option
     { optionType = Nothing,
       optionDescription = Nothing,
-      optionDefault = Nothing
+      optionDefault = Nothing,
+      optionAlternativeDefaults = [],
+      optionRequirement = OptionOptional,
+      optionDocumentedDefault = Nothing
     }
 
 simplifyOption :: Option -> Option
@@ -270,7 +353,7 @@
         _ -> OptionTypeNullOr $ go t
       OptionTypeListOf o -> OptionTypeListOf $ go o
       OptionTypeAttrsOf o -> OptionTypeAttrsOf $ go o
-      OptionTypeOneOf os -> case goEnums $ nubOrd $ concatMap goOr os of
+      OptionTypeOneOf os -> case goEnums $ mergeSubmodules $ nubOrd $ concatMap goOr os of
         [ot] -> ot
         os' ->
           if any canBeNull os'
@@ -304,6 +387,32 @@
             OptionTypeEnum es' -> goEnum (es ++ es') rest
             _ -> t : goEnum es rest
 
+    -- The module system merges a value of a oneOf with the first alternative
+    -- whose check it passes, and that of a submodule only asks for an
+    -- attribute set, so a value for any later submodule would be merged with
+    -- the first one instead.
+    mergeSubmodules :: [OptionType] -> [OptionType]
+    mergeSubmodules ts = case mapMaybe submoduleOptions ts of
+      m : ms@(_ : _) ->
+        let (before, after) = break (isJust . submoduleOptions) ts
+         in concat
+              [ before,
+                [OptionTypeSubmodule $ M.map goOpt $ foldr mergeAlternatives m ms],
+                filter (isNothing . submoduleOptions) after
+              ]
+      _ -> ts
+
+    submoduleOptions :: OptionType -> Maybe (Map Text Option)
+    submoduleOptions = \case
+      OptionTypeSubmodule m -> Just m
+      OptionTypeNull -> Nothing
+      OptionTypeSimple _ -> Nothing
+      OptionTypeEnum _ -> Nothing
+      OptionTypeNullOr _ -> Nothing
+      OptionTypeListOf _ -> Nothing
+      OptionTypeAttrsOf _ -> Nothing
+      OptionTypeOneOf _ -> Nothing
+
     goOpt o = o {optionType = go <$> optionType o}
 
     goOr = \case
@@ -316,9 +425,6 @@
 renderOption :: Option -> Text
 renderOption = renderExpression . withNixArgs . optionExpression
 
-renderOptions :: Map Text Option -> Text
-renderOptions = renderExpression . withNixArgs . optionsExpression
-
 renderOptionType :: OptionType -> Text
 renderOptionType = renderExpression . withNixArgs . optionTypeExpression
 
@@ -330,36 +436,86 @@
 optionExpr = optionExpression
 
 optionExpression :: Option -> Expression
-optionExpression Option {..} =
-  ExprAp
-    (ExprVar "lib.mkOption")
-    ( ExprAttrSet $
-        M.fromList $
-          concat
-            [ [("type", optionTypeExpression typ) | typ <- maybeToList optionType],
-              [("description", ExprLitString d) | d <- maybeToList optionDescription],
-              case optionDefault of
-                Nothing -> case optionType of
-                  -- Automatically give submodule options a default of the empty set.
-                  Just (OptionTypeSubmodule _) -> [("default", ExprAttrSet M.empty)]
-                  _ -> []
-                Just d -> [("default", toNixExpressionViaCodec d)]
-            ]
-    )
-
--- {-# DEPRECATED optionsExpr "Use optionsExpression instead" #-}
-optionsExpr :: Map Text Option -> Expression
-optionsExpr = optionsExpression
-
-optionsExpression :: Map Text Option -> Expression
-optionsExpression = ExprAttrSet . M.map optionExpression
+optionExpression o = bindDefinedSubmodule (maybeToList (optionType o)) $ unboundOptionExpression o
 
 -- {-# DEPRECATED optionTypeExpr "Use optionTypeExpression instead" #-}
 optionTypeExpr :: OptionType -> Expression
 optionTypeExpr = optionTypeExpression
 
 optionTypeExpression :: OptionType -> Expression
-optionTypeExpression = go
+optionTypeExpression t = bindDefinedSubmodule [t] $ unboundOptionTypeExpression t
+
+-- | An option that refers to 'definedSubmoduleName' without binding it.
+unboundOptionExpression :: Option -> Expression
+unboundOptionExpression Option {..} =
+  let inlineNix :: JSON.Value -> String
+      inlineNix d =
+        unwords $
+          map (T.unpack . T.strip) $
+            T.lines $
+              renderExpression $
+                toNixExpressionViaCodec d
+      orList :: [String] -> String
+      orList ws = case reverse ws of
+        [] -> ""
+        [w] -> w
+        lastWord : rest -> unwords [intercalate ", " (reverse rest), "or", lastWord]
+      undefaultedText :: Text
+      undefaultedText = case optionRequirement of
+        OptionRequired -> "None, required"
+        OptionOptional -> case catMaybes optionAlternativeDefaults of
+          [] -> "Unspecified"
+          defaults ->
+            T.pack $
+              concat
+                [ orList $
+                    map (\d -> concat ["`", inlineNix d, "`"]) defaults
+                      ++ ["unspecified" | Nothing `elem` optionAlternativeDefaults],
+                  ", depending on the first alternative that parses"
+                ]
+      -- The documentation gives a submodule no default, and a submodule that
+      -- is not specified leaves each of its options to its own default, so
+      -- there is nothing to say about it.
+      isUnspecifiedSubmodule :: Bool
+      isUnspecifiedSubmodule = case (optionRequirement, optionAlternativeDefaults, optionDocumentedDefault, optionType) of
+        (OptionOptional, [], Nothing, Just (OptionTypeSubmodule _)) -> True
+        (OptionOptional, [], Nothing, Just (OptionTypeNullOr (OptionTypeSubmodule _))) -> True
+        _ -> False
+   in ExprAp
+        (ExprVar "lib.mkOption")
+        ( ExprAttrSet $
+            M.fromList $
+              concat
+                [ [("type", unboundOptionTypeExpression typ) | typ <- maybeToList optionType],
+                  [("description", ExprLitString d) | d <- maybeToList optionDescription],
+                  case optionDefault of
+                    -- The documentation would otherwise give the empty value
+                    -- of the type, like null for a nullOr, as the default.
+                    Nothing ->
+                      [ ( "defaultText",
+                          let text =
+                                ExprAp (ExprVar "lib.literalMD") $
+                                  ExprLitString $
+                                    case optionDocumentedDefault of
+                                      Nothing -> undefaultedText
+                                      Just d -> T.pack $ concat [T.unpack undefaultedText, ", interpreted as `", inlineNix d, "`"]
+                           in -- The documentation keeps the other fields of a
+                              -- defaultText, so that whatever renders it can
+                              -- tell a required option apart without reading
+                              -- the text.
+                              case optionRequirement of
+                                OptionRequired -> ExprUpdate text (ExprAttrSet (M.singleton "required" (ExprLitBool True)))
+                                OptionOptional -> text
+                        )
+                      | not isUnspecifiedSubmodule
+                      ]
+                    Just d -> [("default", toNixExpressionViaCodec d)]
+                ]
+        )
+
+-- | A type that refers to 'definedSubmoduleName' without binding it.
+unboundOptionTypeExpression :: OptionType -> Expression
+unboundOptionTypeExpression = go
   where
     go = \case
       OptionTypeNull -> ExprAp (ExprVar "lib.types.enum") (ExprLitList [ExprNull])
@@ -379,6 +535,145 @@
           (ExprVar "lib.types.oneOf")
           (ExprLitList (map go os))
       OptionTypeSubmodule os ->
-        ExprAp
-          (ExprVar "lib.types.submodule")
-          (ExprAttrSet (M.singleton "options" (optionsExpression os)))
+        let requiredKey :: Text -> Option -> Maybe Expression
+            requiredKey key o = case optionRequirement o of
+              OptionRequired -> Just (ExprLitString key)
+              OptionOptional -> Nothing
+         in ExprAp
+              (ExprAp (ExprVar definedSubmoduleName) (ExprLitList (M.elems (M.mapMaybeWithKey requiredKey os))))
+              (ExprAttrSet (M.map unboundOptionExpression os))
+
+-- | Bind 'definedSubmoduleName' around an expression that uses any of the
+-- given types, once per expression instead of once per submodule.
+bindDefinedSubmodule :: [OptionType] -> Expression -> Expression
+bindDefinedSubmodule ts e =
+  if any hasSubmodule ts
+    then
+      ExprLet
+        ( M.fromList
+            [ (definedSubmoduleName, definedSubmoduleExpression),
+              (definedTypeName, definedTypeExpression)
+            ]
+        )
+        e
+    else e
+
+hasSubmodule :: OptionType -> Bool
+hasSubmodule = \case
+  OptionTypeNull -> False
+  OptionTypeSimple _ -> False
+  OptionTypeEnum _ -> False
+  OptionTypeNullOr t -> hasSubmodule t
+  OptionTypeListOf t -> hasSubmodule t
+  OptionTypeAttrsOf t -> hasSubmodule t
+  OptionTypeOneOf ts -> any hasSubmodule ts
+  OptionTypeSubmodule _ -> True
+
+definedSubmoduleName :: Text
+definedSubmoduleName = "definedSubmodule"
+
+definedTypeName :: Text
+definedTypeName = "definedType"
+
+-- | A function from the required keys and the option declarations of a
+-- submodule to a submodule type that 'definedTypeExpression' makes of it.
+definedSubmoduleExpression :: Expression
+definedSubmoduleExpression =
+  ExprLam "required" $
+    ExprLam "declarations" $
+      ExprAp
+        (ExprAp (ExprVar definedTypeName) (ExprVar "required"))
+        (ExprAp (ExprVar "lib.types.submodule") (ExprAttrSet (M.singleton "options" (ExprVar "declarations"))))
+
+-- | A function from the required keys of a submodule type and that type to a
+-- submodule type whose value is what was defined in it: the options that were
+-- defined, and the required ones whether they were or not.
+--
+-- Reading an option that was not defined does not throw when its type has an
+-- empty value, like null for a nullOr or [ ] for a listOf, so a required
+-- option throws itself.
+-- Which options were defined is read from the evaluated submodule that the v2
+-- merge of nixpkgs returns next to the value.
+-- Its merge is changed, rather than anything reading the value, so that it
+-- also covers a submodule nested in any other type, because those merge their
+-- elements with the element type's merge.
+-- The module system rebuilds the type of an option from its submodules, so the
+-- type it ends up with is made the same way.
+-- It cannot be merged with another declaration of the same option, because
+-- the result would be a plain submodule, whose value is not what was defined.
+-- Its functor has a name of its own so that a plain submodule cannot be merged
+-- with it either.
+-- It has no empty value, so that reading an option of this type that has no
+-- definitions throws instead of giving every option of the submodule.
+definedTypeExpression :: Expression
+definedTypeExpression =
+  let apply :: Text -> [Expression] -> Expression
+      apply f = foldl ExprAp (ExprVar f)
+      submodule :: Text -> Expression
+      submodule = ExprSelect (ExprVar "submodule")
+      optionOf :: Expression
+      optionOf = apply "lib.getAttr" [ExprVar "name", ExprVar "options"]
+      requiredValue :: Expression
+      requiredValue =
+        ExprLam "name" $
+          ExprIf
+            (ExprAp (ExprVar "isDefined") (ExprVar "name"))
+            (ExprAp (ExprVar "configValue") (ExprVar "name"))
+            ( apply
+                "throw"
+                [ apply
+                    "lib.concatStrings"
+                    [ ExprLitList
+                        [ ExprLitString "The option `",
+                          ExprAp (ExprVar "lib.showOption") (ExprSelect optionOf "loc"),
+                          ExprLitString "' is required but was not defined."
+                        ]
+                    ]
+                ]
+            )
+      -- The submodule's own merge calls the v2 merge of what it is part of
+      -- when it is called as a function, so only the v2 merge is replaced.
+      mergeV2 :: Expression
+      mergeV2 =
+        ExprLam "args" $
+          ExprLet
+            ( M.fromList
+                [ ("merged", ExprAp (ExprSelect (submodule "merge") "v2") (ExprVar "args")),
+                  ("options", ExprSelect (ExprSelect (ExprSelect (ExprVar "merged") "valueMeta") "configuration") "options"),
+                  ("isDefined", ExprLam "name" (ExprSelect optionOf "isDefined")),
+                  ("configValue", ExprLam "name" (apply "lib.getAttr" [ExprVar "name", ExprSelect (ExprVar "merged") "value"])),
+                  ("requiredValue", requiredValue)
+                ]
+            )
+            ( ExprUpdate (ExprVar "merged") $
+                ExprAttrSet $
+                  M.singleton "value" $
+                    ExprUpdate
+                      (apply "lib.genAttrs" [ExprVar "required", ExprVar "requiredValue"])
+                      ( apply
+                          "lib.genAttrs"
+                          [ apply
+                              "lib.filter"
+                              [ ExprVar "isDefined",
+                                apply "lib.attrNames" [apply "lib.removeAttrs" [ExprVar "options", ExprLitList [ExprLitString "_module"]]]
+                              ],
+                            ExprVar "configValue"
+                          ]
+                      )
+            )
+   in ExprLam "required" $
+        ExprLam "submodule" $
+          ExprUpdate (ExprVar "submodule") $
+            ExprAttrSet $
+              M.fromList
+                [ ("merge", ExprUpdate (submodule "merge") (ExprAttrSet (M.singleton "v2" mergeV2))),
+                  ("emptyValue", ExprAttrSet M.empty),
+                  ( "substSubModules",
+                    ExprLam "modules" $
+                      ExprAp
+                        (ExprAp (ExprVar definedTypeName) (ExprVar "required"))
+                        (ExprAp (submodule "substSubModules") (ExprVar "modules"))
+                  ),
+                  ("typeMerge", ExprLam "_" ExprNull),
+                  ("functor", ExprUpdate (submodule "functor") (ExprAttrSet (M.singleton "name" (ExprLitString definedSubmoduleName))))
+                ]
