From f96d6886c8a33d91f5aa3107b448b659fc6daa27 Mon Sep 17 00:00:00 2001
From: tomvanmele <tom.v.mele@gmail.com>
Date: Thu, 3 Oct 2024 16:32:39 +0200
Subject: [PATCH] close to final draft

---
 docs/devguide/dtypes.rst | 72 +++++++++++++++++++++++++++++++++++++---
 1 file changed, 67 insertions(+), 5 deletions(-)

diff --git a/docs/devguide/dtypes.rst b/docs/devguide/dtypes.rst
index e7891f1d753..3d494be775c 100644
--- a/docs/devguide/dtypes.rst
+++ b/docs/devguide/dtypes.rst
@@ -102,16 +102,78 @@ True
 Attribute types
 ===============
 
+Any attribute that is an instance of a Python base type or a serializable COMPAS data object
+can be included in the data dict created by the ``__data__`` property without further processing.
+The serialization process will take care of all required conversions automatically.
 
-Data schema
-===========
+.. code-block:: python
+
+    class CustomData(Data):
+        
+        def __init__(self, point, frame, mesh, name=None):
+            super().__init__(name=name)
+            self.point = point
+            self.frame = frame
+            self.mesh = mesh
+
+        @property
+        def __data__(self):
+            return {
+                "point": self.point,
+                "frame": self.frame,
+                "mesh": self.mesh,
+            }
+
+
+>>> import compas
+>>> from compas.geometry import Point, Frame
+>>> from compas.datastructures import Mesh
+>>> point = Point(1, 2, 3)
+>>> frame = Frame()
+>>> mesh = Mesh.from_meshgrid(10, 10)
+>>> custom = CustomData(point, frame, mesh)
+>>> compas.json_dump(custom, "custom.json")
+>>> result = compas.json_load("custom.json")
+>>> isinstance(result.point, Point)
+True
+>>> isinstance(result.frame, Frame)
+True
+>>> isinstance(result.mesh, Mesh)
+True
+>>> result.point == point
+True
+>>> result.point is point
+False
+
+
+Note that when many instances of a type like this have to serialized/deserialized,
+letting the encoders and decoders that care of this automatically,
+can unnecessarily increase the size of the JSON file.
 
-Optionally, you can provide a data schema that describes
-the internal serialization data of your class more precisely.
+To avoid this, anticipated conversions can be included explicitly in `__data__` and `__from_data__`.
 
 .. code-block:: python
 
     class CustomData(Data):
+        
+        def __init__(self, point, frame, mesh, name=None):
+            super().__init__(name=name)
+            self.point = point
+            self.frame = frame
+            self.mesh = mesh
 
-        DATASCHEMA = {}
+        @property
+        def __data__(self):
+            return {
+                "point": self.point.__data__,
+                "frame": self.frame.__data__,
+                "mesh": self.mesh.__data__,
+            }
 
+        @classmethod
+        def __from_data__(cls, data):
+            return cls(
+                Point.__from_data__(data['point']),
+                Frame.__from_data__(data['frame']),
+                Mesh.__from_data__(data['mesh3']),
+            )