From 71211ad2e767a48fbc5208876f54263e9506a8c2 Mon Sep 17 00:00:00 2001
From: James McKinney <26463+jpmckinney@users.noreply.github.com>
Date: Tue, 17 Oct 2023 21:47:10 -0400
Subject: [PATCH] docs: Document that "/" in JSON keys can cause collisions,
 closes #767

---
 agate/table/from_object.py             | 19 +++++++++++++++++++
 examples/test_from_json_ambiguous.json |  8 ++++++++
 tests/test_from_json.py                |  8 ++++++++
 3 files changed, 35 insertions(+)
 create mode 100644 examples/test_from_json_ambiguous.json

diff --git a/agate/table/from_object.py b/agate/table/from_object.py
index f5357f05..f114e918 100644
--- a/agate/table/from_object.py
+++ b/agate/table/from_object.py
@@ -40,6 +40,25 @@ def from_object(cls, obj, row_names=None, column_types=None):
     Not all rows are required to have the same keys. Missing elements will
     be filled in with null values.
 
+    Keys containing a slash (``/``) can collide with other keys. For example:
+
+    .. code-block:: python
+
+        {
+            'a/b': 2,
+            'a': {
+                'b': False
+            }
+        }
+
+    Would generate:
+
+    .. code-block:: python
+
+        {
+            'a/b': false
+        }
+
     :param obj:
         Filepath or file-like object from which to read JSON data.
     :param row_names:
diff --git a/examples/test_from_json_ambiguous.json b/examples/test_from_json_ambiguous.json
new file mode 100644
index 00000000..5435946e
--- /dev/null
+++ b/examples/test_from_json_ambiguous.json
@@ -0,0 +1,8 @@
+[
+    {
+        "a/b": 2,
+        "a": {
+            "b": false
+        }
+    }
+]
diff --git a/tests/test_from_json.py b/tests/test_from_json.py
index e880e153..63ba0602 100644
--- a/tests/test_from_json.py
+++ b/tests/test_from_json.py
@@ -1,5 +1,6 @@
 from agate import Table
 from agate.data_types import Boolean, Date, DateTime, Number, Text, TimeDelta
+from agate.rows import Row
 from agate.testcase import AgateTestCase
 from agate.type_tester import TypeTester
 
@@ -85,3 +86,10 @@ def test_from_json_no_type_tester(self):
     def test_from_json_error_newline_key(self):
         with self.assertRaises(ValueError):
             Table.from_json('examples/test.json', newline=True, key='test')
+
+    def test_from_json_ambiguous(self):
+        table = Table.from_json('examples/test_from_json_ambiguous.json')
+
+        self.assertColumnNames(table, ('a/b',))
+        self.assertColumnTypes(table, [Boolean])
+        self.assertRows(table, [Row([False])])