diff --git a/Library/Homebrew/cmd/outdated.rb b/Library/Homebrew/cmd/outdated.rb
index c64d81561b0c97392dc41656b1d93376be2e81ec..3c6290d635c120ff80ad5499ccc3fae2ded30133 100644
--- a/Library/Homebrew/cmd/outdated.rb
+++ b/Library/Homebrew/cmd/outdated.rb
@@ -22,11 +22,9 @@ module Homebrew
       switch :verbose,
              description: "Include detailed version information."
       flag   "--json",
-             description: "Print output in JSON format. Currently the default and only accepted "\
-                          "value for <version> is `v1`. See the docs for examples of using the JSON "\
-                          "output: <https://docs.brew.sh/Querying-Brew>. "\
-                          "By default, this option treats all arguments as formulae. "\
-                          "To treat arguments as casks, use the --cask option."
+             description: "Print output in JSON format. There are two versions: v1 and v2. " \
+                          "v1 is deprecated and is currently the default if no version is specified. " \
+                          "v2 prints outdated formulae and casks. "
       switch "--fetch-HEAD",
              description: "Fetch the upstream repository to detect if the HEAD installation of the "\
                           "formula is outdated. Otherwise, the repository's HEAD will only be checked for "\
@@ -48,6 +46,8 @@ module Homebrew
 
     case json_version
     when :v1
+      opoo "JSON v1 has been deprecated. Please use --json=v2"
+
       outdated = if args.formula? || !args.cask?
         outdated_formulae
       else
diff --git a/docs/Manpage.md b/docs/Manpage.md
index 5a2b8f7919136a2af35559267a375df9204099f7..d2d2262a917a6af42cec621b9a9085344f298978 100644
--- a/docs/Manpage.md
+++ b/docs/Manpage.md
@@ -356,7 +356,7 @@ otherwise.
 * `-v`, `--verbose`:
   Include detailed version information.
 * `--json`:
-  Print output in JSON format. Currently the default and only accepted value for *`version`* is `v1`. See the docs for examples of using the JSON output: <https://docs.brew.sh/Querying-Brew>. By default, this option treats all arguments as formulae. To treat arguments as casks, use the --cask option.
+  Print output in JSON format. There are two versions: v1 and v2. v1 is deprecated and is currently the default if no version is specified. v2 prints outdated formulae and casks. 
 * `--fetch-HEAD`:
   Fetch the upstream repository to detect if the HEAD installation of the formula is outdated. Otherwise, the repository's HEAD will only be checked for updates when a new stable or development version has been released.
 * `--greedy`:
diff --git a/manpages/brew.1 b/manpages/brew.1
index 012d48c9961a3b638eb7d70a3076fdae5ecea584..5ad417cc91d950cc6d00d2244abd9ea8921ef924 100644
--- a/manpages/brew.1
+++ b/manpages/brew.1
@@ -477,7 +477,7 @@ Include detailed version information\.
 .
 .TP
 \fB\-\-json\fR
-Print output in JSON format\. Currently the default and only accepted value for \fIversion\fR is \fBv1\fR\. See the docs for examples of using the JSON output: \fIhttps://docs\.brew\.sh/Querying\-Brew\fR\. By default, this option treats all arguments as formulae\. To treat arguments as casks, use the \-\-cask option\.
+Print output in JSON format\. There are two versions: v1 and v2\. v1 is deprecated and is currently the default if no version is specified\. v2 prints outdated formulae and casks\.
 .
 .TP
 \fB\-\-fetch\-HEAD\fR