chore: improve docs on arbitrary json

hanxiao · hanxiao · commit 397d349bf3d5 · 2022-03-16T17:57:34.000+01:00
diff --git a/docs/fundamentals/document/construct.md b/docs/fundamentals/document/construct.md
@@ -28,7 +28,7 @@ str(uuid.UUID(d.id))
 
 Though possible, it is not recommended modifying `.id` of a Document frequently, as this will lead to unexpected behavior.
 
-
+(construct-from-dict)=
 ## Construct with attributes
 
 This is the most common usage of the constructor: initializing a Document object with given attributes.
@@ -135,7 +135,7 @@ When using in Jupyter notebook/Google Colab, Document is automatically prettifie
 ```{figure} images/doc-in-jupyter.png
 ```
 
-
+(unk-attribute)=
 ### Unknown attributes handling
 
 If you give an unknown attribute (i.e. not one of the built-in Document attributes), they will be automatically "caught" into `.tags` attributes. For example,
diff --git a/docs/fundamentals/document/serialization.md b/docs/fundamentals/document/serialization.md
@@ -45,7 +45,6 @@ print(d_as_json, d)
 
 By default, it uses {ref}`JSON Schema and pydantic model<schema-gen>` for serialization, i.e. `protocol='jsonschema'`. You can switch the method to `protocol='protobuf'`, which leverages Protobuf as the JSON serialization backend.
 
-To load an arbitrary JSON file, please set `protocol=None`. But as it is "arbitrary", you should not expect it can be succesfully loaded. DocArray tries its best reasonable effort by first load this JSON into `dict` and then load it via `Document(dict)`.
 
 ```python
 from docarray import Document
@@ -95,6 +94,22 @@ To find out what extra parameters you can pass to `to_json()`/`to_dict()`, pleas
 - [`protocol='protobuf', **kwargs`](https://googleapis.dev/python/protobuf/latest/google/protobuf/json_format.html#google.protobuf.json_format.MessageToJson)
 ```
 
+
+(arbitrary-json)=
+
+### From/to arbitrary JSON
+
+Arbitrary JSON is unschema-ed JSON. It often comes from a handcrafted JSON, or an export file from other libraries. Its schema is unknown to DocArray, so by principle we can not load it.
+
+But load it, we do. To load an arbitrary JSON file set `protocol=None`. 
+
+As an _arbitrary_ JSON, you should not expect it always works smoothly. DocArray will try its best reasonable effort to parse its fields: by first loading the JSON into a `dict` object; and then building a Document via `Document(dict)`; when encountering unknown attributes it follows the behavior {ref}`described here<unk-attribute>`.
+
+Rule of thumb, if you only work inside DocArray's ecosystem, please always prefer schema-ed JSON (`.to_json(protocol='jsonschema')`, or `.to_json(protocol='protobuf')`) over unschema-ed JSON. If you are exporting DocArray's JSON to other ecosystems, also prefer schema-ed JSON. Your engineer friends will appreciate it as it is easier for integration. In fact, DocArray does **not** unschema-ed JSON export, and your engineer friends will never be upset.
+
+Read more about {ref}`schema-gen` support in DocArray.
+
+
 (doc-in-bytes)=
 ## From/to bytes
 
diff --git a/docs/fundamentals/documentarray/serialization.md b/docs/fundamentals/documentarray/serialization.md
@@ -68,6 +68,8 @@ da_r.summary()
 
 
 ```{seealso}
+To load an arbitrary JSON file, please set `protocol=None` {ref}`as descrbied here<arbitrary-json>`.
+
 More parameters and usages can be found in the Document-level {ref}`doc-json`.
 ```
 
