feat: add basic document description fields

Signed-off-by: Cesar Berrospi Ramis <[email protected]>

Author: ceberam

docling_core/types/doc/document.py

@@ -4,6 +4,7 @@
 import mimetypes
 import re
 import typing
+from datetime import datetime
 from io import BytesIO
 from typing import Any, Dict, Final, List, Optional, Tuple, Union
 
@@ -23,7 +24,7 @@
 from typing_extensions import Annotated, Self
 
 from docling_core.search.package import VERSION_PATTERN
-from docling_core.types.base import _JSON_POINTER_REGEX
+from docling_core.types.base import _JSON_POINTER_REGEX, UniqueList
 from docling_core.types.doc import BoundingBox, Size
 from docling_core.types.doc.labels import DocItemLabel, GroupLabel
 from docling_core.types.legacy_doc.tokens import DocumentToken
@@ -757,7 +758,16 @@ class PageItem(BaseModel):
 
 
 class DescriptionItem(BaseModel):
-    """DescriptionItem."""
+    """Metadata fields describing a document."""
+
+    title: Optional[str] = None
+    author: Optional[str] = None
+    company: Optional[str] = None
+    category: Optional[str] = None
+    keywords: Optional[UniqueList[str]] = None
+    comment: Optional[str] = None
+    created: Optional[datetime] = None
+    modified: Optional[datetime] = None
 
 
 class DoclingDocument(BaseModel):
@@ -767,7 +777,7 @@ class DoclingDocument(BaseModel):
     version: Annotated[str, StringConstraints(pattern=VERSION_PATTERN, strict=True)] = (
         CURRENT_VERSION
     )
-    description: DescriptionItem
+    description: Optional[DescriptionItem] = None
     name: str  # The working name of this document, without extensions
     # (could be taken from originating doc, or just "Untitled 1")
     origin: Optional[DocumentOrigin] = (

test/test_docling_doc.py

@@ -1,4 +1,5 @@
 from collections import deque
+from datetime import datetime, timezone
 
 import pytest
 import yaml
@@ -410,3 +411,56 @@ def test_version_doc():
         description=DescriptionItem(), name="Untitled 1", version=comp_version
     )
     assert doc.version == CURRENT_VERSION
+
+
+def test_description_item():
+    # no description
+    doc = DoclingDocument(name="Test document")
+    assert doc.description is None
+
+    # set description
+    desc = DescriptionItem(
+        title=(
+            "DocLayNet: A Large Human-Annotated Dataset for Document-Layout " "Analysis"
+        ),
+        author=(
+            "Birgit Pfitzmann, Christoph Auer, Michele Dolfi, Ahmed S. Nassar, and "
+            "Peter Staar"
+        ),
+        company="IBM Research",
+        category=(
+            "-  Information systems  ->  Document structure; -  Applied computing  "
+            "->  Document analysis; -  Computing methodologies  ->  Machine learning; "
+            "Computer vision; Object detection;"
+        ),
+        keywords=[
+            "PDF document conversion",
+            "layout segmentation",
+            "object-detection",
+            "data set",
+            "Machine Learning",
+        ],
+        created=datetime(
+            year=2022,
+            month=6,
+            day=15,
+            hour=12,
+            minute=57,
+            second=56,
+            tzinfo=timezone.utc,
+        ),
+        modified=datetime.now(tz=timezone.utc),
+    )
+    doc = DoclingDocument(description=desc, name="Test document")
+    assert doc.description is not None
+
+    # incompatible keywords
+    with pytest.raises(ValidationError, match="unique"):
+        desc = DescriptionItem(
+            keywords=["Machine Learning", "Machine Learning", "layout segmentation"]
+        )
+
+    # good and wrong date casting
+    desc = DescriptionItem(created="2024-10-16", modified=1729077211.437628)
+    with pytest.raises(ValidationError, match="valid datetime"):
+        desc = DescriptionItem(created=False)