DoclingDocument Version Compatibility Strategy

Generated against library versions v2.36.0 – v2.85.0, schema versions 1.4.0 → 1.10.0 (50 releases).

Part 1 — Change Taxonomy: Last 50 Releases

Overview

In 50 library releases the schema version field embedded in every DoclingDocument JSON was only bumped 6 times (1.4 → 1.5 → 1.6 → 1.7 → 1.8 → 1.9 → 1.10), yet there were 36 individual schema-touching commits. 30 of those 36 shipped additive model changes without any schema version bump and without any downgrade-projection companion.

Category legend

Count summary (50-release vs 30-release window)

Zero required-field additions in all 50 releases. Every breaking change is either a new optional field or a new enum value — confirming that the entire problem space is solvable with two targeted changes (see Part 2).

Schema version discipline — full history

Commit-level classification

v2.36 – v2.56 (new in 50-release window)

Part 2 — Recommended Architecture

Problem framing

DoclingDocument has two independent versions:

The existing check_version_is_compatible validator raises a hard ValueError when doc.minor > sdk.minor, and NodeItem carries model_config = ConfigDict(extra="forbid"), so any unknown field also crashes immediately. Both are correctness guards, but they make clients brittle against additive server changes.

Layer 1 — Make the client a Tolerant Reader (highest leverage)

The single most impactful change. Requires only a docling-core upgrade on the client; no server-side negotiation needed.

1a. Enum coercion via BeforeValidator

Replace bare enum validation on fields like content_layer with a coercing wrapper that falls back gracefully and emits a warning instead of crashing:

# In document.py (or a shared compat module)
def _coerce_content_layer(v: object) -> object:
    """Accept any unknown enum value; log a warning and fall back to BODY."""
    if isinstance(v, str) and v not in ContentLayer._value2member_map_:
        import logging
        logging.getLogger(__name__).warning(
            "Unknown ContentLayer value %r — treating as BODY", v
        )
        return ContentLayer.BODY
    return v

# On NodeItem:
content_layer: Annotated[
    ContentLayer, BeforeValidator(_coerce_content_layer)
] = ContentLayer.BODY

This applies equally to DocItemLabel, CodeLanguageLabel, PictureClassificationLabel, and any other enum field on a serialised model.

1b. Switch extra="forbid" → extra="ignore" on NodeItem

class NodeItem(BaseModel):
    model_config = ConfigDict(extra="ignore")   # was "forbid"

Unknown fields from a newer server are silently dropped instead of crashing. This alone handles every "new optional field" case observed in the 50-release analysis.

Trade-off: extra="ignore" means typos in field names during construction are also silently dropped. Mitigate by keeping extra="forbid" in unit tests (inject a strict config via a test fixture) or by running strict validation only at construction time, not at wire-deserialization time.

1c. Soften the version validator

Downgrade from a hard error to a warning for same-major, higher-minor documents:

@field_validator("version")
@classmethod
def check_version_is_compatible(cls, v: str) -> str:
    sdk_match = re.match(VERSION_PATTERN, CURRENT_VERSION)
    doc_match = re.match(VERSION_PATTERN, v)
    if doc_match is None or sdk_match is None:
        raise ValueError(f"Cannot parse version {v!r}")
    sdk_major = int(sdk_match["major"])
    doc_major, doc_minor = int(doc_match["major"]), int(doc_match["minor"])
    sdk_minor = int(sdk_match["minor"])
    if doc_major != sdk_major:
        raise ValueError(
            f"Doc major version {doc_major} != SDK major {sdk_major}: incompatible."
        )
    if doc_minor > sdk_minor:
        warnings.warn(
            f"Doc schema {v} is newer than SDK schema {CURRENT_VERSION}. "
            "Unknown fields and enum values will be ignored.",
            UserWarning,
            stacklevel=2,
        )
    return v   # keep the original version — do not overwrite with SDK version

Preserving the original version string (rather than overwriting with CURRENT_VERSION) lets downstream code inspect what schema version was actually received.

Layer 2 — Server-side downgrade projectors

Every schema minor bump must be accompanied by a registered projector that can reduce a newer document to one parseable by the previous minor version. Ship a docling_core/compat.py module:

# docling_core/compat.py
from packaging.version import Version

_projectors: dict[tuple[int, int], callable] = {}

def register_projector(from_minor: int, to_minor: int):
    """Decorator: register a function that downgrades from_minor → to_minor."""
    def decorator(fn):
        _projectors[(from_minor, to_minor)] = fn
        return fn
    return decorator

def project_to(doc: "DoclingDocument", target_version: str) -> "DoclingDocument":
    """Return a copy of doc projected to be parseable by target_version SDK."""
    target = Version(target_version)
    current = Version(doc.version)
    data = doc.model_dump(mode="python")
    for minor in range(int(current.minor), int(target.minor), -1):
        fn = _projectors.get((minor, minor - 1))
        if fn:
            data = fn(data)
    from docling_core.types.doc.document import DoclingDocument
    return DoclingDocument.model_validate(data)

# Example — ships alongside the 1.11.0 schema bump:
@register_projector(from_minor=11, to_minor=10)
def _project_1_11_to_1_10(data: dict) -> dict:
    """Map SOCIAL content layer to BODY for clients at schema 1.10."""
    for item in data.get("texts", []):
        if item.get("content_layer") == "social":
            item["content_layer"] = "body"
    data["version"] = "1.10.0"
    return data

The server reads an Accept-Schema-Version request header and runs the projection chain before returning JSON:

# Server-side (conceptual)
doc: DoclingDocument = converter.convert(pdf)
client_version = request.headers.get("Accept-Schema-Version", CURRENT_VERSION)
if Version(client_version) < Version(doc.version):
    doc = project_to(doc, target_version=client_version)
return doc.model_dump_json()

Rule: Every schema minor bump (1.10 → 1.11) must be accompanied by a @register_projector function committed in the same PR. Enforce this with a unit test that asserts len(_projectors) == CURRENT_MINOR - 1.

Layer 3 — Schema version advertisement (low cost, optional)

Expose the server's schema version in a capabilities or health endpoint so clients can check proactively:

GET /capabilities
{
  "docling_core_version": "2.86.0",
  "document_schema_version": "1.10.0",
  "min_compatible_schema_version": "1.0.0"
}

The client reads this on startup and logs a warning (or refuses to start) if the server's schema version is ahead of the client's CURRENT_VERSION.

Change classification and version-bump rules

Formalise in CONTRIBUTING.md:

Summary

Bottom line: The two-mechanism Tolerant Reader fix (extra="ignore" + BeforeValidator on enum fields) is sufficient for 100% of the observed breaking-change space across all 50 releases analysed. No required-field addition has ever appeared. The downgrade-projector layer additionally handles future new DocItem subtypes (4 occurrences in 50 releases) where the client truly cannot process a feature at all.

Conclusion

The following sections describe 3 possible layers (non-exclusive) for compatibility. Since we want to keep the benefits of strict validation and keep the compatibility logic in the server system, we will proceed with the implementation of the Layer 2 as remediation strategy.

As part of the solution, we will need to:

• automate the downgrade projectors as much as possible
• add validation scripts in the CI/CD
• coordinate the downgrade projectors and DoclingDocument versioning with Doclang