Merge pull request #188 from lsst/tickets/DM-55343

DM-55343: Remove minimum length on description field

Author: JeremyMcCormick

docs/changes/DM-55343.api.rst

@@ -0,0 +1 @@
+Removed restriction on the minimum length of the description field.

python/felis/datamodel.py

@@ -81,12 +81,6 @@
 https://docs.pydantic.dev/2.0/api/config/#pydantic.config.ConfigDict
 """
 
-DESCR_MIN_LENGTH = 3
-"""Minimum length for a description field."""
-
-DescriptionStr: TypeAlias = Annotated[str, Field(min_length=DESCR_MIN_LENGTH)]
-"""Type for a description, which must be three or more characters long."""
-
 
 class BaseObject(BaseModel):
     """Base model.
@@ -104,15 +98,17 @@ class BaseObject(BaseModel):
     id: str = Field(alias="@id")
     """Unique identifier of the database object."""
 
-    description: DescriptionStr | None = None
+    description: str | None = None
     """Description of the database object."""
 
     votable_utype: str | None = Field(None, alias="votable:utype")
     """VOTable utype (usage-specific or unique type) of the object."""
 
     @model_validator(mode="after")
     def check_description(self, info: ValidationInfo) -> BaseObject:
-        """Check that the description is present if required.
+        """Check that the description is present and contains at least one
+        non-whitespace character, if the validation context indicates that this
+        check is enabled. By default, descriptions may be omitted or empty.
 
         Parameters
         ----------
@@ -129,8 +125,6 @@ def check_description(self, info: ValidationInfo) -> BaseObject:
             return self
         if self.description is None or self.description == "":
             raise ValueError("Description is required and must be non-empty")
-        if len(self.description) < DESCR_MIN_LENGTH:
-            raise ValueError(f"Description must be at least {DESCR_MIN_LENGTH} characters long")
         return self
 
 

tests/test_datamodel.py

@@ -122,41 +122,146 @@ def test_validation(self) -> None:
         with self.assertRaises(ValidationError):
             Column(**units_data)
 
-    def test_description(self) -> None:
-        """Test Pydantic validation of the ``description`` attribute."""
+    def test_description_unchecked(self) -> None:
+        """Test that the ``description`` attribute is optional when the
+        ``check_description`` flag is disabled (the default).
+        """
+        # A missing description should be allowed.
+        col = Column.model_validate(
+            {
+                "name": "testColumn",
+                "@id": "#test_col_id",
+                "datatype": "string",
+                "length": 256,
+            }
+        )
+        self.assertIsNone(col.description)
+
+        # An explicit 'None' description should be allowed.
+        col = Column.model_validate(
+            {
+                "name": "testColumn",
+                "@id": "#test_col_id",
+                "datatype": "string",
+                "length": 256,
+                "description": None,
+            }
+        )
+        self.assertIsNone(col.description)
+
+        # An empty description should be allowed.
+        col = Column.model_validate(
+            {
+                "name": "testColumn",
+                "@id": "#test_col_id",
+                "datatype": "string",
+                "length": 256,
+                "description": "",
+            }
+        )
+        self.assertEqual(col.description, "")
+
+        # A description with only whitespace should be allowed.
+        col = Column.model_validate(
+            {
+                "name": "testColumn",
+                "@id": "#test_col_id",
+                "datatype": "string",
+                "length": 256,
+                "description": "   ",
+            }
+        )
+
+        # Pydantic will strip this automatically.
+        self.assertEqual(col.description, "")
+
+        # A description with one or more non-whitespace characters should be
+        # allowed.
+        col = Column.model_validate(
+            {
+                "name": "testColumn",
+                "@id": "#test_col_id",
+                "datatype": "string",
+                "length": 256,
+                "description": "x",
+            }
+        )
+        self.assertEqual(col.description, "x")
+
+    def test_description_checked(self) -> None:
+        """Test Pydantic validation of the ``description`` attribute when the
+        ``check_description`` flag is enabled.
+        """
+        cxt = {"check_description": True}
+
         # Creating a column with a description of 'None' should throw.
-        with self.assertRaises(ValueError):
-            Column(
-                **{
+        with self.assertRaises(ValidationError):
+            Column.model_validate(
+                {
                     "name": "testColumn",
                     "@id": "#test_col_id",
                     "datatype": "string",
+                    "length": 256,
                     "description": None,
-                }
+                },
+                context=cxt,
             )
 
         # Creating a column with an empty description should throw.
-        with self.assertRaises(ValueError):
-            Column(
-                **{
+        with self.assertRaises(ValidationError):
+            Column.model_validate(
+                {
                     "name": "testColumn",
                     "@id": "#test_col_id",
                     "datatype": "string",
+                    "length": 256,
                     "description": "",
-                }
+                },
+                context=cxt,
             )
 
-        # Creating a column with a description that is too short should throw.
+        # Creating a column with a whitespace-only description should throw,
+        # since whitespace is stripped before validation.
         with self.assertRaises(ValidationError):
-            Column(
-                **{
+            Column.model_validate(
+                {
                     "name": "testColumn",
                     "@id": "#test_col_id",
                     "datatype": "string",
-                    "description": "xy",
-                }
+                    "length": 256,
+                    "description": "   ",
+                },
+                context=cxt,
             )
 
+        # Creating a column with a single non-whitespace character in the
+        # description should not throw.
+        col = Column.model_validate(
+            {
+                "name": "testColumn",
+                "@id": "#test_col_id",
+                "datatype": "string",
+                "length": 256,
+                "description": "x",
+            },
+            context=cxt,
+        )
+        self.assertEqual(col.description, "x")
+
+        # Creating a column with more than one non-whitespace character in the
+        # description should not throw.
+        col = Column.model_validate(
+            {
+                "name": "testColumn",
+                "@id": "#test_col_id",
+                "datatype": "string",
+                "length": 256,
+                "description": "test description",
+            },
+            context=cxt,
+        )
+        self.assertEqual(col.description, "test description")
+
     def test_values(self) -> None:
         """Test Pydantic validation of the ``value`` attribute."""