diff --git a/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md b/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md
index 40e652c84a..c9b6ebca1f 100644
--- a/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md
+++ b/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md
@@ -50,6 +50,49 @@ When one and only one of multiple argument are required:
 
   :::
 
+## Non-argument `val` channel inputs
+
+Input channel `val` declarations MAY be used to control behaviours of the module that cannot be expressed with arguments of the underlying tool.
+
+- If a module can output multiple file formats, the output format SHOULD be provided through a channel. The module SHOULD NOT infer the output format from the input path.
+  :::info{title="Rationale" collapse}
+  Modules can encounter numerous input name scenarios. Custom string operations necessarily make assumptions about the name of the file (for example that the name of a compressed file has at least two dots). Providing an explicit format input returns full control to the pipeline developer and reduces the risk of unexpected behaviour.
+  :::
+
+  :::info{title="Example" collapse}
+
+  ```nextflow
+  # incorrect
+  out_file = "${prefix}.${in_file.name.split('.')[1]}.gz"
+  # correct
+  out_file = "${prefix}.${out_ext}.gz"
+  ```
+
+  :::
+
+- If the output format of a module is necessarily the same as the input format, the module MAY infer the output format from the input path.
+
+- If a module contains an optional pipe (for example: compression, sorting), the pipe SHOULD be controlled with a Boolean input channel.
+  :::info{title="Example" collapse}
+
+  ```nextflow
+  input:
+  ...
+  val compress
+
+  script:
+  compress_cmd = compress ? "| gzip" : ""
+  """
+  tool $in_file $compress_cmd > $out_file
+  """
+  ```
+
+  :::
+
+- If a module has an explicit output format, this format MAY be used to control compression.
+
+Non-standard `ext` fields (example: `ext.suffix`) SHOULD NOT be used to control module behaviour. `val` inputs SHOULD NOT be used for subcommands, separate modules SHOULD be used instead.
+
 ## Output channel emissions
 
 Named file extensions MUST be emitted for ALL output channels.