Balisage Paper: DGML: Semantic XML for the Age of Document AI

The Token Problem

Every token sent to a language model costs money, consumes context, and dilutes the model's attention. Three obvious candidates for representing a business document to an LLM each have a structural problem in that economy.

The Trust Problem

The token problem is the half of this story the field already discusses. The other half goes largely unaddressed: once an agent is not merely reading a document but acting on it — approving a payment, certifying compliance, computing a net asset value from a thousand underlying leases — the fragment the agent consumed becomes evidence, and someone downstream will eventually ask not whether the file was authentic, but whether this specific clause, this specific number, was exactly what the source said.

Existing attestation practice does not answer that question at the granularity agents operate at. A signed PDF, a notarized file, a blockchain hash of a whole document all certify the file as a unit — sufficient to prove a document has not been altered since it was filed, useless for proving that the $500,000 figure an agent extracted from page 14 is the same $500,000 figure that was in the signed original. Agents read and cite fragments, not files; a certification scheme pitched at the file level protects a boundary the agent never touches.

DGML sets out to close both gaps with one architecture: a format economical enough to feed a model, and provable enough — down to a single data element — that an agent's fragment can be trusted without producing, or even seeing, the rest of the document it came from.

Docsets: One Vocabulary, an Entire Corpus

A docset is a named collection of documents of the same type produced by a specific organization — all Master Services Agreements issued by one counterparty, or all invoices from one supplier. The docset defines the tag vocabulary: which element names exist, what they mean, and how they relate to one another. Documents belong in the same docset when they serve the same functional purpose and share 70–80% of their semantic fields with consistent meaning; they are split into separate docsets when field semantics diverge, issuing organizations differ, or a document type has changed enough over time that old and new versions can no longer be compared field-by-field.

Concept-Driven Naming

Only elements that carry a genuine domain concept receive a semantic tag. Every other structural role — headings, lists, list items, table cells, enumerators, an inline run with no resolved concept — is emitted as the generic dg:chunk element, with its visual role recorded in a dg:structure attribute (section, header, p, ol, li, table, tr, td, and two DGML-specific values, lim for a verbatim enumerator and span for an unresolved inline run). This is the defining rule of DGML element naming: a wrong semantic tag is worse than an honest dg:chunk. dg:chunk also serves as the document root.

A representative fragment from a Master Services Agreement:

                     
<dg:chunk xmlns:dg="http://dgml.io/ns/dg#"
          xmlns:docset="http://www.dgml.io/acme-corp/master-services-agreements#"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <docset:IndemnificationClause>
    <docset:IndemnifyingParty dg:origin="2 460 310 1800 355">Vendor</docset:IndemnifyingParty>
    <docset:LiabilityCap xsi:type="decimal" dg:value="500000"
                         dg:origin="2 460 410 1800 455">$500,000</docset:LiabilityCap>
    <docset:EffectiveDate xsi:type="date" dg:value="2024-01-01"
                          dg:origin="2 998 710 1466 755">January 1, 2024</docset:EffectiveDate>
  </docset:IndemnificationClause>
</dg:chunk>

Note the typed value convention: xsi:type carries a standard XSD type name, dg:value carries the canonical machine-readable form, and the element's text content preserves the display form exactly as it appeared in the source. An agent can query docset:LiabilityCap/@dg:value across a thousand contracts using identical logic — that cross-document consistency, not any single document's tagging, is DGML's headline property.

Hello, DGML: A Minimal Complete Document

Stripped to its smallest form, a DGML document is a namespaced element tree with typed values and a semantic link — nothing more is required for a file to be valid DGML:

                     
<dg:chunk xmlns:dg="http://dgml.io/ns/dg#"
          xmlns:docset="http://www.dgml.io/acme-corp/master-services-agreements#">

  <docset:VendorName xml:id="vendor">MagicSoft, Inc.</docset:VendorName>

  <docset:IndemnificationClause>
    <docset:LiabilityCap xsi:type="decimal" dg:value="500000">$500,000</docset:LiabilityCap>
  </docset:IndemnificationClause>

  <docset:SignatoryName
      dg:itemprop="signatoryOf" dg:href="#vendor">Jane Smith</docset:SignatoryName>

</dg:chunk>

Everything else in this paper — pixel provenance, attestation, browser rendering, graph export — is additive: attributes and packaging that layer onto this same tree as the documents, and the stakes, get real.

Authored by Models, Not Just Read by Them

The tag machinery described so far — namespaced elements, a docset-level vocabulary, typed values — is not, on its own, new. What is new is who is capable of authoring and applying it. Building a semantic vocabulary for a document type, and then tagging a corpus against it, has traditionally depended on a human information architect to design the tag set and a human cataloguer — or a team of them — to apply it document by document. That work is careful and often excellent, but it does not scale with the number of document types or the number of documents an organization holds, and that cost is a large part of why semantic markup has stayed confined to well-funded corpora rather than becoming the default representation of business documents at large.

What has changed is that a model can now do this first-pass work itself. Given a set of documents, a model can group them into docsets — clustering documents that share a functional purpose and a common set of semantic fields — read a representative sample of each, and surface the concepts that actually recur across it: the parties, dates, amounts, and clauses that make up the document type's real structure, as distinct from its visual layout. From that reading, the model drafts the docset's schema.rnc (section “Schema Definition in RELAX NG Compact Syntax”) and tags documents against it directly, producing the vocabulary and the tagged XML together, at a scale no team of human information architects and catalogers could match.

A schema drafted this way can stand on its own. DGML also leaves room for people to tweak it when they want to: it can be annotated with ## Prompt: comments to tell a model where a field typically appears, or how a computed value is derived — a lightweight refinement, not a required step.

The reference implementation released alongside this paper runs that workflow end to end: point it at a folder of source PDFs and it groups them into docsets, drafts schema.rnc from what it reads across the corpus, and tags the documents — applying dg:origin, xsi:type/dg:value, and dg:itemprop/dg:href as it goes — largely without a person in the loop at either step. That a model can discover a corpus's semantic structure and produce both the schema and the tagged XML at scale, with a working implementation to show for it, is the claim this paper makes — not that namespaces or typed values themselves are new.

Semantic Layer

Consistent tags across similar documents let an agent reason over a corpus without per-document prompt engineering. Each tag groups many surface tokens into a single named concept, and any XML element subtree can be sent to a model in isolation to focus its attention precisely — a single clause instead of an entire contract.

Spatial Layer

Every element may carry a dg:origin attribute recording where its content can be found in the rendered source page images:

                     
dg:origin="<page> <x1> <y1> <x2> <y2>"

Coordinates are 1-based page numbers and pixel offsets in raster space (origin top-left, y increasing downward), matching a page_images/page_N.png rendered at a declared DPI. Multiple boxes, separated by semicolons, express a value spanning lines or pages. On a leaf element dg:origin pins one value; on a parent it spans the full extent of the subtree, so a viewer can highlight an entire clause as well as a single field. A reserved value, dg:origin="computed", marks a field whose value is derived from other elements rather than read directly from the page; such a field always pairs with dg:itemprop/dg:href pointing to its sources.

Extracted values are consequently not floating assertions — each can be shown to a human as a highlighted rectangle on the original document. This is the difference between an answer and a verifiable answer. Stripping dg:origin before a model call — it exists for grounding, not reasoning — is itself a further 20–40% token reduction.

Attestation Layer

The deeper novelty for this audience is fragment-level attestation. The conventional blockchain use case hashes an entire document and anchors that single hash on-chain as proof of origin for the whole file. DGML goes further: because the semantic tree is structured, any XML element subtree — a single data point, a payment term, a liability cap — can be hashed and anchored independently, proving that specific data artifact's origin without producing the entire document.

An element stake commits to a single XML element together with an inclusion proof tying it to the document root without revealing any other element. The element's canonical hash is

                     
checksum = SHA-256( exclusive_C14N(element) )

using Exclusive Canonical XML 1.0 so that the hash is independent of inherited namespace context: the same element hashes identically whether staked standalone or inside a full document. The proof itself is a standard binary Merkle audit path in the sense of RFC 6962 [Laurie, Langley, and Kasper 2013] — the same construction used by Certificate Transparency logs — carrying a leaf hash, a 0-based DFS pre-order leaf index, the total leaf count, and an ordered list of sibling hashes:

                     
candidate = SHA-256( exclusive_C14N(element) )
if candidate != proof.leaf_hash: return False   # the element itself changed
current = candidate
for step in proof.path:
    current = SHA-256( step.sibling + current )     if step.side == "L"
              SHA-256( current + step.sibling )      if step.side == "R"
return current == root_hash

A failed verification distinguishes two cases cleanly: if the re-hashed element differs from proof.leaf_hash, the element itself changed; if the element hash matches but the path fails to reconstruct root_hash, the tree around it changed. Only O(log N) sibling hashes are needed, so the full document is never stored or transmitted to verify one fragment.

File-level anchoring composes with element-level anchoring rather than duplicating it: a file stake hashes four independent slots — the source bytes, each rendered page image, the RELAX NG schema, and the DGML XML itself — into one RFC 6962 Merkle root using the same construction as element staking, so a file-level record and an element-level record drawn from the same document are cryptographically consistent by construction, not by convention.

Readable Layer

A DGML file is readable in any browser with no special viewer. Some elements — not every element — carry a dg:structure attribute recording a structural role drawn from a small, closed vocabulary (section, p, table, span, and a handful of others — no arbitrary HTML), and an optional dg:style attribute — a semicolon-separated list of standard CSS declarations, emitted only when the styling is visually evident in the source — copies verbatim into an HTML style attribute. Neither aims at full-fidelity reproduction of the original layout: the goal is a document a person can open, read, and understand, not a pixel-perfect facsimile of the source. A few lines of transform are enough to render a DGML document as a readable web page with no knowledge of the docset schema required, and combined with dg:origin a viewer can also overlay an element's bounding box on the original page image.

Namespaces and Root

Key Attributes

Four Layers

Docsets and Packaging