Expand block model docstrings

Author: ml-evs

pydatalab/schemas/cell.json

@@ -176,7 +176,7 @@
   "definitions": {
     "DataBlockResponse": {
       "title": "DataBlockResponse",
-      "description": "A generic response model for a block, i.e., what is stored in `self.data`\nin the corresponding DataBlock class.",
+      "description": "A generic response model for a block, i.e., what is stored in `self.data`\nin the corresponding DataBlock class.\n\nIt is expected but not mandatory that this model will be extended by the specific block type\nwhere possible.",
       "type": "object",
       "properties": {
         "blocktype": {

pydatalab/schemas/equipment.json

@@ -140,7 +140,7 @@
   "definitions": {
     "DataBlockResponse": {
       "title": "DataBlockResponse",
-      "description": "A generic response model for a block, i.e., what is stored in `self.data`\nin the corresponding DataBlock class.",
+      "description": "A generic response model for a block, i.e., what is stored in `self.data`\nin the corresponding DataBlock class.\n\nIt is expected but not mandatory that this model will be extended by the specific block type\nwhere possible.",
       "type": "object",
       "properties": {
         "blocktype": {

pydatalab/schemas/sample.json

@@ -229,7 +229,7 @@
     },
     "DataBlockResponse": {
       "title": "DataBlockResponse",
-      "description": "A generic response model for a block, i.e., what is stored in `self.data`\nin the corresponding DataBlock class.",
+      "description": "A generic response model for a block, i.e., what is stored in `self.data`\nin the corresponding DataBlock class.\n\nIt is expected but not mandatory that this model will be extended by the specific block type\nwhere possible.",
       "type": "object",
       "properties": {
         "blocktype": {

pydatalab/schemas/startingmaterial.json

@@ -282,7 +282,7 @@
     },
     "DataBlockResponse": {
       "title": "DataBlockResponse",
-      "description": "A generic response model for a block, i.e., what is stored in `self.data`\nin the corresponding DataBlock class.",
+      "description": "A generic response model for a block, i.e., what is stored in `self.data`\nin the corresponding DataBlock class.\n\nIt is expected but not mandatory that this model will be extended by the specific block type\nwhere possible.",
       "type": "object",
       "properties": {
         "blocktype": {

pydatalab/src/pydatalab/models/blocks.py

@@ -6,6 +6,9 @@
 class DataBlockResponse(BaseModel):
     """A generic response model for a block, i.e., what is stored in `self.data`
     in the corresponding DataBlock class.
+
+    It is expected but not mandatory that this model will be extended by the specific block type
+    where possible.
     """
 
     blocktype: str
@@ -39,16 +42,20 @@ class DataBlockResponse(BaseModel):
     """Any warnings that occurred during block processing."""
 
     b64_encoded_image: dict[PyObjectId, str] | None
-    """Any base64-encoded image data associated with the block, keyed by file_id, if any."""
+    """Any base64-encoded image data associated with the block, keyed by `file_id`."""
 
     bokeh_plot_data: dict | None
     """A JSON-encoded string containing the Bokeh plot data, if any."""
 
     processed_data: dict | None = None
-    """Any processed data associated with the block, small enough to store."""
+    """Any processed data associated with the block, small enough to store and filter directly in the database,
+    i.e., strings or a few hundred numbers not exceeding 16KB in size.
+    Examples could include peak positions, and widths, but not the full spectrum.
+    """
 
     metadata: dict | None = None
-    """Any metadata associated with the block."""
+    """Any structured metadata associated with the block, for example,
+    experimental acquisition parameters."""
 
     class Config:
         allow_population_by_field_name = True