Include Field/SparkField examples in Field metadata

Author: akhsiM

src/sparkdantic/model.py

@@ -206,9 +206,6 @@ def create_json_spark_schema(
         annotation_or_return_type = _get_annotation_or_return_type(info)
         field_type = _get_union_type_arg(annotation_or_return_type)
 
-        description = getattr(info, 'description', None)
-        comment = {'comment': description} if description else {}
-
         spark_type: Union[str, Dict[str, Any]]
 
         try:
@@ -248,7 +245,7 @@ def create_json_spark_schema(
             'name': name,
             'type': spark_type,
             'nullable': nullable,
-            'metadata': comment,
+            'metadata': _json_field_metadata(info),
         }
         fields.append(struct_field)
     return {
@@ -627,3 +624,14 @@ def json_schema_to_ddl(json_schema: Dict[str, Any]) -> str:
         field_ddls.append(field_ddl)
 
     return ','.join(field_ddls)
+
+
+def _json_field_metadata(info: ComputedFieldInfo) -> dict[str, str]:
+    description = getattr(info, 'description', None)
+    metadata = {'comment': description} if description else {}
+
+    examples = getattr(info, 'examples', None)
+    if examples:
+        metadata['examples'] = examples
+
+    return metadata

tests/test_field_descriptions.py

@@ -0,0 +1,90 @@
+from pyspark.sql.types import StringType, StructField, StructType
+
+from sparkdantic import SparkField, SparkModel
+
+
+class DescriptionModel(SparkModel):
+    field_with_description: str = SparkField(description='This is a test description.')
+    field_with_examples: str = SparkField(examples=['test'])
+    field_with_description_and_examples: str = SparkField(
+        description='testing description', examples=['testing example']
+    )
+
+    field_without_metadata: str = SparkField()
+
+
+def test_spark_schema_contains_field_metadata():
+    expected_schema = StructType(
+        [
+            StructField(
+                'field_with_description',
+                StringType(),
+                False,
+                metadata={'comment': 'This is a test description.'},
+            ),
+            StructField(
+                'field_with_examples',
+                StringType(),
+                False,
+                metadata={'examples': ['test']},
+            ),
+            StructField(
+                'field_with_description_and_examples',
+                StringType(),
+                False,
+                metadata={
+                    'comment': 'testing description',
+                    'examples': ['testing example'],
+                },
+            ),
+            StructField(
+                'field_without_metadata',
+                StringType(),
+                False,
+                metadata={},
+            ),
+        ]
+    )
+
+    actual_schema = DescriptionModel.model_spark_schema()
+    print('hmmm')
+    print(actual_schema)
+    assert actual_schema == expected_schema
+
+
+def test_spark_schema_json_contains_field_metadata():
+    expected_json_schema = {
+        'type': 'struct',
+        'fields': [
+            {
+                'name': 'field_with_description',
+                'type': 'string',
+                'nullable': False,
+                'metadata': {'comment': 'This is a test description.'},
+            },
+            {
+                'name': 'field_with_examples',
+                'type': 'string',
+                'nullable': False,
+                'metadata': {'examples': ['test']},
+            },
+            {
+                'name': 'field_with_description_and_examples',
+                'type': 'string',
+                'nullable': False,
+                'metadata': {
+                    'comment': 'testing description',
+                    'examples': ['testing example'],
+                },
+            },
+            {
+                'name': 'field_without_metadata',
+                'type': 'string',
+                'nullable': False,
+                'metadata': {},
+            },
+        ],
+    }
+
+    actual_json_schema = DescriptionModel.model_json_spark_schema()
+    assert actual_json_schema == expected_json_schema