Docling Core

2.73.0 · active · verified Fri Apr 10

Docling Core is a Python library for defining, validating, and structuring data types and schemas. It's designed to align with the Docling specification, offering robust data validation capabilities. Currently at version 2.73.0, it undergoes frequent updates, often with daily or weekly releases in its 2.x series.

Warnings

breaking The `Type` class was removed and replaced by `DataType`. Code using `from docling_core import Type` or instantiating `Type(...)` will break.
Fix: Migrate all `Type` usages to `DataType`. E.g., `from docling_core import DataType`.
breaking The primary exception class for validation errors was renamed from `ValidationError` to `ValidationErrors`.
Fix: Update exception handling: `except ValidationErrors as e:` instead of `except ValidationError as e:`.
breaking The `description` argument for `DataType` classes was renamed to `_description` to avoid potential conflicts with user-defined fields.
Fix: Change `class MyData(DataType, description="...")` to `class MyData(DataType, _description="...")`.
gotcha The `format` argument in `Field` has stricter validation in 2.x and only accepts specific predefined formats (like 'email', 'uri') or a callable validator. Arbitrary strings might no longer work as expected.
Fix: Review `format` usage. Ensure it's one of the supported strings or a callable. Custom format validation might need a separate callable validator.
gotcha By default, `DataType` is strict and will raise `ValidationErrors` if extra fields are provided in the input dictionary that are not defined in the `DataType` schema. Explicitly allow extra fields if needed.
Fix: To allow extra fields, define the DataType with `class MyData(DataType, allow_extra_fields=True):`.

Install

pip install docling-core Install stable version

Imports

DataType
```
from docling_core import DataType
```
The 'Type' class was removed in version 2.0.0 and replaced by 'DataType'.
Field
```
from docling_core import Field
```
ValidationErrors
```
from docling_core import ValidationErrors
```
The 'ValidationError' class was renamed to 'ValidationErrors' in version 2.0.0.

Quickstart

This example defines a `User` data type with `Field` validators for name, age, and email. It demonstrates how to instantiate a `DataType` with valid data and handles validation errors for invalid input.

from docling_core import Field, DataType

class User(DataType):
    name = Field(str, description="The user's full name")
    age = Field(int, min_value=0, description="The user's age")
    email = Field(str, format="email", description="The user's email address")

user_data = {
    "name": "John Doe",
    "age": 30,
    "email": "john.doe@example.com"
}

try:
    user = User(user_data)
    print(f"Validated user: {user.name}, {user.age}, {user.email}")
except Exception as e:
    print(f"Validation error: {e}")

# Example of invalid data
invalid_user_data = {
    "name": "Jane Doe",
    "age": -5,  # Invalid age
    "email": "invalid-email"
}

try:
    User(invalid_user_data)
except Exception as e:
    print(f"Validation error for invalid data: {e}")

view raw JSON →