# DocLang vs K2F

The **K2F format** operates on a dual-state architecture: an editable semantic JSON tree (State A) and a compiled, **pixel stable lock** (`document.K2F.lock` / State C) packaged inside a self-contained ZIP archive. While DocLang extracts and records historical bounding box coordinates from pre-existing visual documents, K2F compiles semantic intent into deterministic geometry using a dedicated Rust reference layout engine (`k2f_layout`), strictly isolating content meaning from visual theme primitives.

K2F is not a lossless superset of DocLang. K2F v0.1 does not import or parse DocLang markup (`.dclg`) or archive packages (`.dclx`), does not import existing PDF files, does not function as an OCR or document ingestion engine, prohibits arbitrary programmatic vector art in State A, lacks native multimodal audio or video tracks, and treats all format exports as read-only projections rather than editable sources.

## At a glance

| Topic | DocLang | K2F |
| :--- | :--- | :--- |
| What the file *is* | AI-native XML markup (`.dclg`) or OPC ZIP archive (`.dclx`) | Semantic JSON tree (State A) + compiled render lock (State C) in a ZIP archive |
| Primary pipeline role | Ingestion, extraction, and context exchange for LLMs and VLMs | Authoring, styling, programmatic editing, and multi-format publishing |
| Pixel-stable pages | No layout compiler; viewers display bounding boxes over raster images or reflow fluid HTML | Yes — viewers paint pre-compiled `document.K2F.lock` directly without reflowing text |
| Node addressing for AI | Non-hierarchical thread IDs (`<thread thread_id="..."/>`), XPath, or visual bounding box coordinates | Mandatory, hierarchical dotted IDs (`parent.child.role`) on every semantic node in State A |
| Programmatic editing | Modifying text desynchronizes coordinates (`<location>`) and bundled page rasters | Agents edit semantic JSON directly; engine recompiles State C deterministically |
| Separation of concerns | Unstyled XML markup; no CSS, no typography rules, and no theme system | Strict separation: zero styling on State A nodes; visual primitives live exclusively in `styles/theme.json` |
| Vector graphics & art | Referenced raster or vector assets via `<picture>`; no vector drawing language | Forbidden in State A JSON; external vector assets stored as SVGs or images in `/assets/` |
| Multi-format publishing | None in specification or reference toolkit; feeds LLM context windows and vector stores | Single-source lock-drawn exports to Microsoft Word (`.docx`), PowerPoint (`.pptx`), PDF AcroForms, and Adobe InDesign (`.idml`) |
| Integrity & signatures | Optional informational `<document_hash>` in `<head>`; no cryptographic signature or viewer banner specification | Cryptographic hashes (`content_hash`, `appearance_hash`), Ed25519 signatures, mandatory viewer banner (`SIGNED`, `UNSIGNED`, `SIGNED_BUT_BROKEN`, `BROKEN_INTEGRITY`, `UNLOCKED`) |
| Import / source of truth | Standard ingestion target for PDF/DOCX via Docling; not an authoring source of truth | `.K2F` is sole source of truth; K2F does not import DocLang (`DOCLANG_IS_NOT_A_SOURCE`) or PDF (`PDF_IS_NOT_A_SOURCE`) |

## DocLang vs K2F: What DocLang is good at

DocLang is purpose-built as an open, standardized data contract for document understanding, multimodal AI ingestion, and RAG pipelines. Its core strengths include:

- **Token-efficient ingestion substrate for LLMs:** Engineered with a compact vocabulary (<1,000 syntax tokens) that maps cleanly to LLM tokenizer vocabularies without prompt bloat. Tables use the Optimized Table Structure Language (OTSL) cell model (`<ched/>`, `<rhed/>`, `<fcel/>`, `<ecel/>`, `<srow/>`, `<nl/>`), reducing token count compared to verbose HTML table tags (e.g., 5 tokens versus 28 tokens).
- **Physical visual grounding and bounding-box alignment:** Preserves spatial context from original scanned documents or PDFs through normalized `<location>` coordinates (`x0, y0, x1, y1`). In `.dclx` archives, these coordinates map directly over bundled page raster images (`pages/*.png`), enabling visual verification and multimodal retrieval in tools like HumanSignal Label Studio and the DocLang Viewer.
- **Specialized document understanding and OCR semantics:** Captures real-world physical artifacts that office formats omit, including handwriting (`<handwriting>`), reading order across multi-column or split-page spans (`<thread>`, `<h_thread>`), checkboxes (`<checkbox class="selected|unselected"/>`), and hierarchical form field regions (`<field_region>`, `<field_item>`, `<key>`, `<value class="fillable">`, `<hint>`).
- **Native multimodal audio and video tracks:** Native support for audio and video transcripts alongside text and tables using unified primitives (`<track>`, `<cover>`, `<frame>`, `<audio>`, `<voice>`, `<chapter>`) with millisecond-precision timestamps (`<hours>`, `<minutes>`, `<seconds>`, `<msecs>`).
- **Embedded governance, provenance, and compliance metadata:** Incorporates machine-readable signals directly in the document `<head>`—such as PII flags, AI training constraints, RAG retrieval permissions, generating model provenance (`<generated_by>`), and document hashes (`<document_hash>`)—avoiding fragile external sidecar files.
- **Open foundation and industry ecosystem:** Standardized under the LF AI & Data Foundation (Linux Foundation) with backing from IBM, NVIDIA, Red Hat, ABBYY, and HumanSignal, natively integrated into document extraction tools such as IBM Research's Docling.

## What K2F adds

K2F addresses the creation and publishing side of the document lifecycle, where AI agents and automated pipelines must author, modify, restyle, and deliver verifiable, pixel-stable documents:

- **Declarative semantic tree & stable dotted IDs:** Every node in State A (`content/root.json`) carries a mandatory, hierarchical dotted ID (e.g., `financials.q3_results.table_revenue` or `contract.clauses.clause_4`). AI agents inspect, target, patch, and diff specific nodes deterministically without navigating ambiguous XML hierarchies, calculating XPath queries, or scraping visual coordinates.
- **Pre-compiled pixel-stable lock (`document.K2F.lock`):** DocLang files contain no layout engine or styling rules, relying on pre-existing raster snapshots or fluid browser reflow. In K2F, the Rust reference engine (`k2f_layout`) runs a deterministic layout pass (`f(content, theme) → geometry`), resolving exact bounding boxes, font embeddings, and glyph positions into an immutable render lock (State C). Official web embedders (`<k2f-viewer>`), the Desktop Reader, and export tools paint this lock directly without re-running layout or reflowing body text.
- **Strict intent-presentation separation:** Content nodes in State A express structure through semantic roles, variants, and closed-enum byte-range modifiers (`emphasis`, `link`, `math`), completely prohibiting inline presentation styles. Visual properties (color palettes, typography, spacing, shadows, corner radii) live exclusively in `styles/theme.json`. Swapping or editing a theme re-skins the entire publication deterministically upon recompilation (`k2f pack`) without risking content corruption or layout drift.
- **Cryptographic provenance & mandatory integrity banners:** K2F establishes end-to-end cryptographic verification via SHA-256 hashes (`content_hash`, `appearance_hash`) and optional Ed25519 digital signatures (`signatures/v1.json`). Official readers enforce a standardized integrity banner displaying five canonical states (`SIGNED`, `UNSIGNED`, `SIGNED_BUT_BROKEN`, `BROKEN_INTEGRITY`, and `UNLOCKED`), while alerting users to runtime layout engine discrepancies (`ENGINE_MISMATCH`). DocLang provides only an informational `<document_hash>` string without a standardized verification or viewer banner protocol.
- **Single-source multi-format enterprise publishing:** While DocLang is an intermediate representation that terminates in LLM context windows, K2F acts as a publication master. The compiled lock renders directly to lock-accurate Microsoft Word (`.docx`), PowerPoint (`.pptx`), interactive PDF (`form_field` nodes export to PDF AcroForms), and Adobe InDesign (`.idml`).
- **Agent tooling and template ecosystem:** K2F provides an official agent skill implementing the `agent_v0` authoring dialect, automated package verification tooling (`pack_verify`), and a public [Gallery](/gallery) of 469+ production-grade templates on [k2f.dev](https://k2f.dev) available without login or subscription fees.

## When to pick which

- **Pick DocLang when:**
  - Ingesting, parsing, and digitizing unstructured documents (scanned PDFs, paper forms, contracts) to feed LLM/VLM context windows or vector databases for RAG and extraction.
  - Document workflows require normalized spatial coordinates (`<location>`) to visually ground extracted text against original page raster images for human annotation or visual question answering.
  - Projects process multimodal recordings containing synchronized audio, video, millisecond timecodes, and speaker tracks alongside text.
  - Toolchains are built around the Linux Foundation LF AI & Data ecosystem (such as IBM Docling or HumanSignal Label Studio).

- **Pick K2F when:**
  - AI agents must author, update, or restyle documents programmatically using stable, hierarchical dotted IDs with strict schema validation and automated verification (`pack_verify`).
  - Organizations need to generate publication-grade business deliverables—reports, proposals, contracts, invoices, fillable forms, and collateral—that export deterministically to Microsoft Word, PowerPoint, PDF AcroForms, and Adobe InDesign from a single source.
  - Workflows require pre-compiled render locks (`document.K2F.lock`), independent theme-based re-skinning without content edits, and cryptographic tamper-evident integrity banners.

- **Exporting from K2F:**
  - Export PDF, Word, PowerPoint, or IDML from `.K2F` when stakeholders require standard office or graphic design deliverables. Export files are read-only drawings of the compiled render lock, not editable sources of truth (`PDF_IS_NOT_A_SOURCE`, `DOCX_IS_NOT_A_SOURCE`, `PPTX_IS_NOT_A_SOURCE`, `IDML_IS_NOT_A_SOURCE`). All structural edits must occur in K2F State A (`content/root.json`).

## Bottom line

For additional details on K2F architecture, explore the technical [documentation](/docs), review pre-built templates in the [Gallery](/gallery), read [why K2F exists](/why), or view the full matrix on [Compare](/compare).

This comparison is based on publicly available information at the time of writing. Capabilities, pricing, and policies may change; verify details with the relevant provider.