API/BUG: Make to_json index= consistent with orient

- split and table allow index=True/False
- records and values only allow index=False
- index and columns only allow index=True
- raise for contradictions in the latter two
- see pandas-dev#25513

Author: dshemetov

pandas/core/generic.py

@@ -2268,7 +2268,7 @@ def to_json(
         default_handler: Callable[[Any], JSONSerializable] | None = None,
         lines: bool_t = False,
         compression: CompressionOptions = "infer",
-        index: bool_t = True,
+        index: bool_t | None = None,
         indent: int | None = None,
         storage_options: StorageOptions = None,
         mode: Literal["a", "w"] = "w",
@@ -2337,10 +2337,17 @@ def to_json(
 
             .. versionchanged:: 1.4.0 Zstandard support.
 
-        index : bool, default True
-            Whether to include the index values in the JSON string. Not
-            including the index (``index=False``) is only supported when
-            orient is 'split' or 'table'.
+        index : bool or None, default None
+            Whether to include the index values in the JSON string. Different
+            defaults and options depend on the 'orient' argument:
+
+                - 'split': default True, can also be False
+                - 'records': default False, cannot be True
+                - 'index': default True, cannot be False
+                - 'columns': default True, cannot be False
+                - 'values': default False, cannot be True
+                - 'table': default True, can also be False
+            
         indent : int, optional
            Length of whitespace used to indent each record.
 

pandas/io/json/_json.py

@@ -140,14 +140,26 @@ def to_json(
     default_handler: Callable[[Any], JSONSerializable] | None = None,
     lines: bool = False,
     compression: CompressionOptions = "infer",
-    index: bool = True,
+    index: bool | None = None,
     indent: int = 0,
     storage_options: StorageOptions = None,
     mode: Literal["a", "w"] = "w",
 ) -> str | None:
-    if not index and orient not in ["split", "table"]:
+    if index is None and orient in ["records", "values"]:
+        index = False
+    elif index is None:
+        index = True
+
+    if not index and orient not in ["split", "table", "records", "values"]:
+        raise ValueError(
+            "'index=False' is only valid when 'orient' is 'split', 'table', " +\
+            "'records', or 'values'"
+        )
+
+    if index and orient in ["records", "values"]:
         raise ValueError(
-            "'index=False' is only valid when 'orient' is 'split' or 'table'"
+            "'index=True' is only valid when 'orient' is 'split', 'table', " +\
+            "'index', or 'columns'. Convert index to column for other orients."
         )
 
     if lines and orient != "records":

pandas/tests/io/json/test_pandas.py

@@ -1476,17 +1476,28 @@ def test_index_false_to_json_table(self, data):
 
         assert result == expected
 
-    @pytest.mark.parametrize("orient", ["records", "index", "columns", "values"])
+    @pytest.mark.parametrize("orient", ["index", "columns"])
     def test_index_false_error_to_json(self, orient):
-        # GH 17394
+        # GH 17394, 25513
         # Testing error message from to_json with index=False
 
         df = DataFrame([[1, 2], [4, 5]], columns=["a", "b"])
 
-        msg = "'index=False' is only valid when 'orient' is 'split' or 'table'"
+        msg = "'index=False' is only valid when 'orient' is 'split', 'table', 'records', or 'values'"
         with pytest.raises(ValueError, match=msg):
             df.to_json(orient=orient, index=False)
 
+    @pytest.mark.parametrize("orient", ["records", "values"])
+    def test_index_true_error_to_json(self, orient):
+        # GH 25513
+        # Testing error message from to_json with index=True
+
+        df = DataFrame([[1, 2], [4, 5]], columns=["a", "b"])
+
+        msg = "'index=True' is only valid when 'orient' is 'split', 'table', 'index', or 'columns'"
+        with pytest.raises(ValueError, match=msg):
+            df.to_json(orient=orient, index=True)
+
     @pytest.mark.parametrize("orient", ["split", "table"])
     @pytest.mark.parametrize("index", [True, False])
     def test_index_false_from_json_to_json(self, orient, index):