Unexpected References Appearing in Docling OCR JSON Results

[manikrishna-m]

Hi Everyone,

I'm using Docling's basic OCR to convert a PDF into text, and I save the output as a JSON file. In one of the PDFs I'm processing, the JSON result includes a group (Group 4), which lists its children as references to texts 61 through 77. Here's a simplified snippet of what the raw JSON looks like:

{
  "children": [
    {"$ref": "#/texts/61"},
    {"$ref": "#/texts/62"},
    {"$ref": "#/texts/63"},
    {"$ref": "#/texts/64"},
    {"$ref": "#/texts/65"},
    {"$ref": "#/texts/66"},
    {"$ref": "#/texts/67"},
    {"$ref": "#/texts/68"},
    {"$ref": "#/texts/69"},
    {"$ref": "#/texts/70"},
    {"$ref": "#/texts/71"},
    {"$ref": "#/texts/72"},
    {"$ref": "#/texts/73"},
    {"$ref": "#/texts/74"},
    {"$ref": "#/texts/75"},
    {"$ref": "#/texts/76"},
    {"$ref": "#/texts/77"}
  ]
}

However, after loading this JSON using:

self.docling_doc = DoclingDocument.model_validate(doc_dict)
The children list in Group 4 unexpectedly changes. Here's what I get:

[
  RefItem(cref='#/texts/61'),
  RefItem(cref='#/texts/62'),
  RefItem(cref='#/texts/63'),
  RefItem(cref='#/texts/64'),
  RefItem(cref='#/texts/65'),
  RefItem(cref='#/texts/66'),
  RefItem(cref='#/texts/67'),
  RefItem(cref='#/texts/68'),
  RefItem(cref='#/groups/45'),  # Unexpected
  RefItem(cref='#/texts/69'),
  RefItem(cref='#/groups/44'),  # Unexpected
  RefItem(cref='#/texts/70'),
  RefItem(cref='#/texts/71'),
  RefItem(cref='#/texts/72'),
  RefItem(cref='#/texts/73'),
  RefItem(cref='#/texts/74'),
  RefItem(cref='#/texts/75')
]

As you can see, there are now references to #/groups/44 and #/groups/45, which were not present in the original JSON. Also, texts/76 and texts/77 are missing from the parsed result.

Can anyone help me understand why this is happening? Is it a parsing issue with model_validate, or could the input JSON be getting altered during validation?

Happy to provide more details if needed.

Thanks in advance!

[dosubot]

This happens because Docling's validation automatically restructures your document if it detects list items that aren't nested inside a group labeled "list". When you run model_validate, Docling inserts new groups (like #/groups/44 and #/groups/45) to enforce its schema, and may drop or reparent some references (such as texts/76 and texts/77) if they don't fit the expected structure. This is by design to maintain document integrity, but it can be surprising if your input isn't already normalized. To avoid this, make sure all list items are nested within a group labeled "list" and that your parent group references this group—this will prevent Docling from auto-correcting your structure and keep your references as expected. You can see more details and examples in this discussion: docling-project/docling/issues/1978.

A recent update to Docling's validation rules may have made this behavior stricter: docling-core/pull/349. If your use case is more complex (like forms), check that your structure matches Docling's schema for those types.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[manikrishna-m]

Hi @dosu,

Thanks for the clear and insightful explanation — the pre-validation check makes a lot of sense.

However, I’m still puzzled by one thing: I’m using the same dictionary structure from the Docling basic OCR parser, but I’m seeing list items appear inside the form_area. Could you help clarify why that might be happening?

Thanks again!

[dosubot]

This happens when the OCR or parsing logic upstream assigns list items as children of a form_area group—it's not something Docling's core validation does on its own. If the parser's output includes list items inside a form_area, Docling will accept that structure, even though it's not the canonical way (normally, list items should be under a list group) see code reference. If you want to avoid this, check your OCR output or intermediate JSON for list items nested under form_area and adjust the parsing logic so list items are grouped under a list group instead. If you want, I can help review a minimal example of your input to suggest a concrete fix.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}