Skip to main content

The axes

The maturity score is a vector: one level per axis, each axis a short ladder. The axes group into three families, named for the question each answers.

Comprehensionhow deeply kapi reads itEngineL0–L4VocabularyV0–V3Structure & GeometryG0–G4ProseP0–P4Assurancehow support is provenCorpusC0–C3SecurityS0–S4Enablementhow people work with itKnowledgeK0–K3EditorE0–E4

The axes in three families.

The grouping is a reading aid. The headline tier is the minimum over the gating axes (Engine, Corpus and Knowledge), one from each family. Security, Structure & Geometry and Prose are non-gating: they score and rank work without entering the tier minimum.

Comprehension: how deeply kapi reads a format​

Three of the Comprehension axes ask one fidelity question at increasing resolution: bytes, then inline meaning, then structure. The fourth, Prose, reads the comments a file carries beside its content.

  • Engine (L0–L4): fidelity of the serialization itself. Does the reader parse the format, round-trip it (the skeleton back byte-for-byte), and, where a reference implementation exists, match it head-to-head? The ladder climbs reads → round-trips → specified → parity-verified → rock-solid.
  • Vocabulary (V0–V3): whether inline meaning (bold, a link, a placeholder) survives into the canonical content model as a typed run, rather than as opaque bytes. The ladder climbs opaque → typed reading → bidirectional → loss-proven. See inline formatting and vocabularies.
  • Structure & Geometry (G0–G4): how much of the document's logical and spatial structure the reader recovers: roles, reading order, tables, and page geometry. It is featured below.
  • Prose (P0–P4): how much of the comment layer kapi can locate, check and rewrite: a comment in a YAML file, a translator comment in a PO file, a doc comment in source code. It is featured below.

Structure & Geometry, by example​

On an image format, every rung recovers more of the page:

G0opaquethe raw asset, no textG1metadatadata about the assetG2Linear body textOCR text, reading orderG3Logical structureheadings, tables, orderG4Spatial geometrypage coords, bounding boxes

Structure & Geometry on an image format: each rung recovers more of the page.

Extracting only the metadata (G1) is shallower than recovering OCR text in reading order (G2), which is shallower than recognizing headings, tables, and reading order (G3), which is shallower than recovering page geometry and bounding boxes (G4). Each rung adds a richer stand-off layer over the content model. Geometry is the top rung because it is the hardest to recover faithfully and, for a translation flow, the least directly useful: logical structure is what the pipeline acts on, while geometry is read-only reconstruction metadata that native writers ignore.

The axis is orthogonal to Engine and Vocabulary: a reader can round-trip bytes perfectly (high Engine) while flattening every page to a single block (G0), and a format with typed inline runs (high Vocabulary) can recover no geometry at all. The vision and PDF readers are where the upper rungs are populated; see the vision and image-adaptation design and the PDF reader design, and try the Structure and layout lab on your own files.

Prose, by rung​

P0Nonecomments are opaque bytesP1Locatedeach comment group has an exact placeP2Governedchecked against the guidance for its placeP3Editablerewritten with every other byte keptP4Completeevery comment form the language uses

Prose: each rung lets kapi do more with the comments in a file.

Prose is scored per language. A format such as YAML or PO has its own row. A source language such as Go has no format of its own, so the dashboard lists it as a language row. A language kapi has no reader for is shown as absent. That differs from a language at P0, where kapi reads the files and leaves their comments untouched.

A rung is awarded only when a test that asserts it passes. A rung test that was skipped or did not build is shown as not run, and awards nothing.

Assurance: how support is proven​

  • Corpus (C0–C3): the reference files that validate support, with provenance: committed exemplars, harvested wild files (license-checked and hash-verified), and synthetic edge-case generators. A varied corpus tests the parser against real documents as well as constructed edge cases. Each file's origin is recorded.
  • Security (S0–S4): how well the parser resists malicious or pathological input: resource budgets, fuzzing, and clean sweeps over a hostile corpus. This axis does not affect the published support tier.

Enablement: working with a format​

  • Knowledge (K0–K3): the specification and learning assets that let a person or a model work on the format correctly from in-repo material alone: a dossier of authoritative spec sources, clauses cited and resolved against pinned snapshots, and a generated context pack.
  • Editor (E0–E4): how close kapi gets to the format's native editing surface: from a faithful, structure-true preview, through a round-trip workflow with stable identity binding, to a live add-in embedded inside the native editor.

Evidence behind each grade​

Each axis level is computed from evidence. A deterministic floor inspects the format's own files and pins each axis level; a model may only demote a small set of quality dimensions, and only with a cited file or test as evidence; it can never promote a level above what the files support. A reproducibility check verifies that repeated runs over the same evidence produce the same vector.

The mechanisms that keep this true as the code, the specifications, and the models change are described in Keeping it alive; the live per-format levels are on the /format-maturity dashboard.