The lists a document is made of

Lesson 4 walked the document in order. Underneath that walk are a handful of flat lists, and knowing which list a piece lives in is how you get at it directly.

A DoclingDocument keeps its content in lists by kind. Every piece of text is in texts, every table in tables, every image in pictures. Those addresses you saw in lesson 4, #/texts/0 and #/tables/0, are literally the list name and the index.

from docling.document_converter import DocumentConverter

converter = DocumentConverter()
document = converter.convert("shipping.md").document
for name in ("texts", "tables", "pictures", "groups"):
    print(name, len(getattr(document, name)))

Six texts, no tables, no pictures and one group. The group is the bullet list: it holds no words of its own, only the two list items that do.

Reaching a piece by its address

print(document.texts[0].text)
print(document.texts[0].self_ref)

The index in the address is the index in the list, so #/texts/0 and document.texts[0] are the same object. That is what makes those addresses useful in a citation: they survive being written to a file and read back.

The same document, a different shape

html = converter.convert("refunds.html").document
for name in ("texts", "tables", "pictures", "groups"):
    print(name, len(getattr(html, name)))

Three texts and one table. The CSV file, converted, has no texts at all and exactly one table. Three formats, one set of field names, and code that walks texts works on all of them.

The group is not in the text list

group = document.groups[0]
print(group.self_ref, group.label)
for ref in group.children:
    print("  ", ref.cref, "|", ref.resolve(document).text)

A group's children are references rather than objects, and resolve turns a reference back into the piece it points at. Docling stores the document flat and links it with these addresses, which is exactly how it can be written to JSON without losing the structure.