Improved docs for read_json table orient

Author: WillAyd

doc/source/io.rst

@@ -1648,7 +1648,7 @@ with optional parameters:
 
   DataFrame
       - default is ``columns``
-      - allowed values are {``split``, ``records``, ``index``, ``columns``, ``values``}
+      - allowed values are {``split``, ``records``, ``index``, ``columns``, ``values``, ``table``}
 
   The format of the JSON string
 
@@ -1732,6 +1732,9 @@ values, index and columns. Name is also included for ``Series``:
   dfjo.to_json(orient="split")
   sjo.to_json(orient="split")
 
+**Table oriented** serializes to the JSON `Table Schema`_, allowing for the
+preservation of metadata including but not limited to dtypes and index names.
+
 .. note::
 
   Any orient option that encodes to a JSON object will not preserve the ordering of
@@ -1848,6 +1851,7 @@ is ``None``. To explicitly force ``Series`` parsing, pass ``typ=series``
      ``values``; just the values array
      ``table``; adhering to the JSON `Table Schema`_
 
+
 - ``dtype`` : if True, infer dtypes, if a dict of column to dtype, then use those, if False, then don't infer dtypes at all, default is True, apply only to the data
 - ``convert_axes`` : boolean, try to convert the axes to the proper dtypes, default is True
 - ``convert_dates`` : a list of columns to parse for dates; If True, then try to parse date-like columns, default is True
@@ -2203,7 +2207,39 @@ A few notes on the generated table schema:
     then ``level_<i>`` is used.
 
 
-_Table Schema: http://specs.frictionlessdata.io/json-table-schema/
+.. versionadded:: 0.23.0
+
+``read_json`` also accepts ``orient='table'`` as an argument. This allows for
+the preserveration of metadata such as dtypes and index names in a
+round-trippable manner.
+
+  .. ipython:: python
+
+   df = pd.DataFrame({'foo': [1, 2, 3, 4],
+		      'bar': ['a', 'b', 'c', 'd'],
+		      'baz': pd.date_range('2018-01-01', freq='d', periods=4),
+		      'qux': pd.Categorical(['a', 'b', 'c', 'c'])
+		      }, index=pd.Index(range(4), name='idx'))
+   df
+   df.dtypes
+
+   df.to_json('test.json', orient='table')
+   new_df = pd.read_json('test.json', orient='table')
+   new_df
+   new_df.dtypes
+
+Please note that the string `index` is not supported with the round trip
+format, as it is used by default in ``write_json`` to indicate a missing index
+name.
+
+.. ipython:: python
+
+   df.index.name = 'index'
+   df.to_json('test.json', orient='table')
+   new_df = pd.read_json('test.json', orient='table')
+   print(new_df.index.name)
+
+.. _Table Schema: http://specs.frictionlessdata.io/json-table-schema/
 
 HTML
 ----

doc/source/whatsnew/v0.23.0.txt

@@ -148,7 +148,7 @@ Current Behavior
 .. _whatsnew_0230.enhancements.round-trippable_json:
 
 JSON read/write round-trippable with ``orient='table'``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 A ``DataFrame`` can now be written to and subsequently read back via JSON while preserving metadata through usage of the ``orient='table'`` argument (see :issue:`18912` and :issue:`9146`). Previously, none of the available ``orient`` values guaranteed the preservation of dtypes and index names, amongst other metadata.
 
@@ -160,35 +160,21 @@ A ``DataFrame`` can now be written to and subsequently read back via JSON while
 		      'qux': pd.Categorical(['a', 'b', 'c', 'c'])
 		      }, index=pd.Index(range(4), name='idx'))
    df
+   df.dtypes
+   df.to_json('test.json', orient='table')
+   new_df = pd.read_json('test.json', orient='table')
+   new_df
+   new_df.dtypes
 
-Previous Behavior:
-
-.. code-block:: ipython
-
-   In [17]: df.to_json("test.json", orient='columns')
-   In [17]: pd.read_json("test.json", orient='columns')
-   Out[18]:
-       bar          baz  foo qux
-   0   a  1514764800000    1   a
-   1   b  1514851200000    2   b
-   2   c  1514937600000    3   c
-   3   d  1515024000000    4   c
-
-Current Behavior:
-
-.. code-block:: ipython
+Please note that the string `index` is not supported with the round trip format, as it is used by default in ``write_json`` to indicate a missing index name.
 
-   In [29]: df.to_json("test.json", orient='table')
-   In [30]: pd.read_json("test.json", orient='table')
-   Out[30]:
-       bar        baz  foo qux
-   idx
-   0     a 2018-01-01    1   a
-   1     b 2018-01-02    2   b
-   2     c 2018-01-03    3   c
-   3     d 2018-01-04    4   c
+.. ipython:: python
 
-Please note that the string `index` is not supported with the round trip format, as it is used by default in ``write_json`` to indicate a missing index name.
+   df.index.name = 'index'
+   df.to_json('test.json', orient='table')
+   new_df = pd.read_json('test.json', orient='table')
+   new_df
+   print(new_df.index.name)
 
 .. _whatsnew_0230.enhancements.other:
 

pandas/io/json/json.py

@@ -339,6 +339,15 @@ def read_json(path_or_buf=None, orient=None, typ='frame', dtype=True,
     -------
     result : Series or DataFrame, depending on the value of `typ`.
 
+    Notes
+    -----
+    Specific to ``orient='table'``, if a ``DataFrame`` with a literal ``Index``
+    name of `index` gets written with ``write_json``, the subsequent read
+    operation will incorrectly set the ``Index`` name to ``None``. This is
+    because `index` is also used by ``write_json`` to denote a missing
+    ``Index`` name, and the subsequent ``read_json`` operation cannot
+    distinguish between the two.
+
     See Also
     --------
     DataFrame.to_json