Pydantic-Based Extraction Templates#

In docling-graph, a template is a plain Python file of Pydantic models that tells the extraction pipeline what entities and relationships to find in a document and how to write them into a knowledge graph. Every structural decision — which models become graph nodes, how nodes are identified for deduplication, and which fields become edges — is expressed through standard Pydantic primitives (ConfigDict, Field, json_schema_extra), not through a separate DSL or configuration layer.

Core Configuration Fields#

Three custom model_config keys control graph structure 1:

At conversion time, GraphConverter reads these values through the get_model_config_value() helper 2. The NodeIDRegistry._generate_fingerprint() method then 3:

• Entities (graph_id_fields set): fingerprint from the declared identity fields only, enabling stable deduplication across extraction batches.
• Components (is_entity=False): fingerprint from all non-empty scalar fields, giving content-based deduplication without a named identity.

Entities vs. Components#

Entities become graph nodes. They need graph_id_fields set to required, scalar, short, verbatim-copyable values — ideally one field, two at most 4. The identity key must be something the document actually names; never instruct the model to invent one, because invented IDs differ between batches and break deduplication 5.

class Organization(BaseModel):
    model_config = ConfigDict(graph_id_fields=["name"])
    name: str = Field(...)

Components (is_entity=False) are value objects embedded inside the nearest entity ancestor — no node is created for them 6. Use them for addresses, monetary amounts, tax brackets, and any value that only makes sense in context of its parent entity. Entities nested inside components still become full nodes; their edge is attached to the nearest enclosing entity, not the component wrapper 7.

class Address(BaseModel):
    model_config = ConfigDict(is_entity=False)
    street: str = Field(...)
    city: str = Field(...)

The practical rule: components cost nothing in the extraction catalog; entities each add a discovery pass and a fill pass 8.

Edge Definitions#

Relationships become graph edges through the edge() helper, which must appear identically in every template 9:

def edge(label: str, **kwargs: Any) -> Any:
    return Field(..., json_schema_extra={"edge_label": label}, **kwargs)

The edge_label key in json_schema_extra is the contract point the converter reads 10. Labels must be ALL_CAPS_WITH_UNDERSCORES verb phrases 11. List edges require default_factory=list 12.

Reference edges — fields that link to an entity by identity only, without extracting its full attributes — add reference=True, which sets json_schema_extra={"graph_reference": True} 13. Reference fields have no discovery path in Phase 1; the parent's fill call emits them as ID-only objects, and graph assembly resolves those onto the canonical node. This avoids the three major failure modes of full nested entities: per-parent membership collapse, parent drift, and catalog explosion 14.

File Organization#

Templates follow a strict declaration order so forward-reference errors are impossible 15:

1. Imports
2. edge() helper
3. Helper/utility functions
4. Components (is_entity=False)
5. Reusable entities (e.g., Person, Organization)
6. Domain-specific models
7. Root document model (last)

The root model is the extraction entry point and always has graph_id_fields set 16.

Key Design Rules (Quick Reference)#

• Identity fields: required, scalar, ≤2 fields, verbatim-copyable, never invented 17
• All non-identity fields: optional (| None or default_factory=list) — required non-identity fields cause all-or-nothing validation loss on smaller models 18
• Docstrings: front-load the discriminating sentence in the first ~240 chars; Phase 1 only sees those 240 chars for entity classification 19
• Validators: normalize, never reject; use mode="before" to coerce what LLMs actually emit 20
• One canonical home per entity: if the same rich model appears at multiple paths, all but one should use reference=True 21
• graph_max_instances: set to ~2× the documented maximum on classes prone to over-discovery 22

Primary References#