Most document work that reaches an AI agent has already been flattened. A PDF of an architectural drawing, a scanned datasheet, a standards document dense with clause numbering and nested tables: by the time it lands in a model's context it is usually a text dump. Someone ran extraction or OCR, concatenated the strings, and handed over a wall of characters. For prose, that is fine. For layout-rich documents it quietly deletes the part that carried the meaning.

Geometry is information. On a floor plan, a label three millimetres from a wall segment belongs to that wall; the same label centred in a room means something else. Reading order in a two-column standard is not top to bottom, and a naive dump interleaves the columns and turns a requirement into nonsense. A table is a grid of relationships, not a run of cells. Strip those out and the model is left reasoning over a transcription that lost exactly the structure a human uses to read the page. This is not a corner case for us. We build verifiable digital passports for buildings, where the source material is drawings, spec sheets, and regulatory PDFs, and where the geometry and the tables are the content, not the decoration.

So the question we set out to answer was narrow and practical: what is the right way to put a layout-rich document in front of an AI agent?

One candidate is DocLang. It is an open, AI-native markup format for unstructured content, designed to preserve structure, semantics, layout, and geometry rather than throw them away. It is real and current: doclang==0.7.2 on PyPI, Apache-2.0, governed under the LF AI & Data Foundation, the vendor-neutral open-source home that also hosts a number of production ML projects. The geometry is not hand-waving. A DocLang document places content with location blocks: coordinates on a resolution grid, 512 by 512 by default, with layers that separate body content from background and furniture. A drawing's spatial relationships survive into the markup.

Here is the nuance most write-ups miss, and it matters. The DocLang toolkit does not convert anything. Its public surface is two functions, pack() and validate(), plus a matching CLI. pack() takes an already-authored DocLang markup file and zips it into a .dclx archive, an OPC container from the same family as .docx. validate() runs the schema and rules. There is no unpack(), and there is no PDF, DOCX, or OCR importer anywhere in the package. Hand the toolkit a real PDF and it has nothing to do with it.

The converter is a separate project: IBM's Docling. Docling does the hard part, parsing PDFs, Office files, and scanned images with layout analysis, reading-order detection, table structure (via a dedicated table model), and OCR, and it can export DocLang directly. So the honest pipeline is two tools, not one:

PDF / DOCX / scan  ->  Docling (OCR, layout, tables)  ->  .dclg markup
                   ->  doclang pack / validate         ->  .dclx  ->  model

In code, the front end is small:

from docling.document_converter import DocumentConverter

doc = DocumentConverter().convert("drawing.pdf").document
doc.save_as_doclang_archive("drawing.dclx")   # writes the OPC archive directly

and the toolkit is what stands behind it as the validator and packager:

doclang validate document.xml     # runs XSD, then Schematron
doclang pack document.xml -o out.dclx

Docling is the engine; DocLang is the representation it emits and the toolkit checks. Naming that split correctly is half the battle, because plenty of material treats "DocLang" as if it ingests your documents. It does not. If you plan around the toolkit alone, you will get to the first PDF and stop.

Here it stops being a tidy tooling story. The model we run is natively multimodal. It does not need a text transcription of a page. You can hand it the page image, or the PDF itself, and it reads the layout, the tables, and the drawing with its vision path. So structured markup is not competing against raw text alone. Its real competitor is the picture.

That reframes the whole evaluation. The interesting question is not "does DocLang beat an OCR dump," which it almost certainly does. It is "does structured text markup beat simply showing the model the page." And the answer is not obvious, because the two approaches trade off on different axes.

Native vision is expensive in tokens. Feeding a document as pages means each page is processed as an image as well as text, and the vendor documentation is blunt that this costs far more than clean extracted text: by one published comparison of text-extraction against full visual processing, on the order of seven times more for the same pages. Guidance from the same source is to convert to text or markdown first precisely to avoid image-based tokenization. Across a corpus of multi-page passport documents, in an agent loop that re-reads its context on every step, that multiplier is a real bill and a real pressure on the context window.

So DocLang's opening is not "more accurate." It is quality-per-token. If structured markup preserves enough geometry to answer the same questions at a fraction of the token cost of feeding the raw image, it wins on the frontier that matters for a production agent. If native vision already recovers the geometry well enough, then for exactly the drawings and schematics we care most about, the extra moving parts of a Docling-to-DocLang pipeline may not earn their place. That is the intellectual core of this, and it is open.

We did not stop at a plan. We ran install spikes, and then a preliminary version of the evaluation itself, before writing the conclusion down.

What installs and runs. On CPython 3.14.6 with uv, doclang==0.7.2 installs clean, and so does its optional Saxon validation backend, saxonche==13.0.0, a prebuilt wheel with no C toolchain. IBM Docling, docling==2.109.0, installs on the same interpreter, though it pulls a heavyweight machine-learning stack, a multi-gigabyte download once the CUDA and Torch wheels land, and its DocLang export path runs live: a conversion produced valid DocLang markup and a round-tripped .dclx archive. One gap shapes any product plan: DocLang ships no renderer, so turning a .dclx back into something a person can read is work you own.

What the interim numbers say. We ran the token, validation, archive, and reasoning scenarios against a real but unrepresentative corpus: the DocLang project's own 44 valid and 59 invalid example files, not building passports, so treat the numbers as directional. Validation is effectively free and correct. Schema-only checks ran in about four milliseconds per file, full schema-plus-rules in about twenty, and every one of the 59 malformed files was rejected. Packing round-tripped losslessly on all 44. The token result was the blunt one. Measured with a consistent tokenizer, DocLang markup ran to a median of roughly twelve times the token count of the same document's plain text, and not one file came within the ten-percent overhead people sometimes hope for. DocLang is not a way to save tokens. It is a way to keep structure, and structure costs.

The reasoning result was the one worth sitting with. We asked the model the same questions from flattened text and from DocLang markup, and had a different model grade the answers blind, because a model asked to grade work in its own style tends to flatter it. On this small set the two arms were almost even. The model answered questions about tables, empty cells, and text split across pages correctly from the flattened dump too. DocLang's only clear win was geometry: asked for the coordinates of an element, the plain-text arm scored zero, because the coordinates simply are not in the text, while the markup arm had them. That is a genuine result and a narrowing one. On small text-and-table documents a strong model does not seem to need the structure spelled out. Where DocLang uniquely helps is exactly where the information is spatial and a text dump cannot carry it.

What is still open, plainly. We have not settled the question this whole post is about, because the decisive arm is still missing: DocLang markup against the native page image, on real drawings, scored for quality per token. The model can already see the page, and our interim run compared markup only against text, not against vision. The corpus was the project's own fixtures, not the dense, multi-page passports we actually care about. Fix both and the answer turns from a guess into a measurement. Until then, adopting DocLang is a preliminary yes for geometry-heavy documents and an open question everywhere else.

The architecture is promising, and the reason is fit, not novelty. We build infrastructure whose whole point is that a claim can be checked later. A document representation that keeps geometry and structure, validates against a published schema, and packs into an inspectable archive suits that posture far better than an opaque text dump or a screenshot. If it clears the vision test, DocLang is a clean layer for layout-faithful document AI, the kind you want under a building passport that a buyer, an insurer, or a regulator might one day audit.

But the adoption decision is gated, and we are keeping it gated. Promising is not proven. The three-arm test decides it, and native vision is a serious competitor that we intend to measure rather than assume away. If structure loses on quality-per-token for the documents we care about, we will say so and reach for the picture.

If you are feeding layout-rich documents to an agent and quietly assuming the geometry did not matter, it probably did. We are working through this in the open, mistakes included. If you have already run the structure-versus-vision comparison on real documents, or you think we are about to learn something the hard way, we would like to hear it.

DocLang, the specification and reference toolkit: github.com/doclang-project/doclang. IBM Docling, the converter that parses your documents and emits DocLang: github.com/docling-project/docling.

I write about AI-native documents, verifiable infrastructure, and agent systems as metaend. If you want to reach me, build on any of this, or tell me where it breaks, the door is here:

metaend on Quilibrium

More writing lives at paragraph.com/@metaend.

If you care whether your own content is legible to machines and agents, that is the question metaend Grade is built to answer: metaend-grade.fly.dev.

Written by metaend.