DocuShell
PProduct HuntLaunch offer: reserve 1 month of Pro free before limited slots open.Reserve free Pro

Parse Output

OKF Export

Set okf=true on any Parse request to receive a conformant Open Knowledge Format (OKF) v0.1 bundle alongside the usual artifacts. A bundle is a directory of Markdown concept documents that AI agents, catalogs, and humans can all read — anchored to the source by SHA-256 fingerprint.

Reference8 min
View as Markdown
Parse PDFReview the base parse endpoint OKF rides on.Enable OKFAdd okf=true and download the .okf.zip bundle.Evidence anchoringSee how source anchoring is recorded in the bundle.

Spec

OKF v0.1

Open, vendor-neutral, Apache 2.0.

Output

.okf.zip

Markdown concepts plus indexes.

Lock-in

None

A bundle is just a folder of files.

Overview

What OKF Is

The Open Knowledge Format (OKF) is an open specification for representing knowledge as a directory of Markdown files with YAML frontmatter. It was published by Google Cloud under the Apache 2.0 license and is not tied to any model provider, database, or agent framework.

DocuShell is a producer of conformant OKF v0.1 bundles. When you set okf=true, the parsed document is emitted as a self-describing knowledge bundle instead of a single Markdown blob — typed concepts, navigable indexes, cross-links, and citations that point back to the source of record.

  • Human- and agent-readable: no SDK or query language stands between a reader and the content.
  • Diffable and reviewable: a bundle lives in git like source code.
  • Portable: ship it as a tarball, mount it from any filesystem, or sync it to any system that speaks files.
  • Composable: browse the same bundle in Obsidian, Notion, MkDocs, or load it into an LLM context.
OKF is the format; DocuShell is one producer of it. Bundles you generate stay readable with or without DocuShell.

Structure

Inside An OKF Bundle

Each bundle is a self-contained directory. Reserved index.md files make it navigable; frontmatter makes it queryable.

The document concept carries the parsed Markdown body plus a # Provenance and # Citations section. The source concept records the original file and its SHA-256 fingerprint. Root and per-directory index.md files support progressive disclosure so an agent can navigate one level at a time.

  • index.md — bundle map with the declared okf_version.
  • log.md — chronological generation history.
  • documents/<slug>.md — the parsed document as a typed concept.
  • references/source.md — the source file, fingerprint, and anchoring verdict.

Implementation

Enable OKF Output

Add a single multipart field to any parse request. The completed job exposes an okf_bundle_download link next to the usual artifacts.

Submit a parse job with OKF output

bash

curl -X POST "https://api.docushell.com/api/v1/parse" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@./acme-q3-earnings.pdf;type=application/pdf" \
  -F "okf=true"
`okf=true` works alongside `output_mode` and `formats`. DocuShell ensures a Markdown-family artifact and JSON are available for the bundle, chunking, and automation.

Completed job artifacts

json

{
  "artifacts": {
    "markdown_download": "/v1/jobs/<id>/download?format=markdown",
    "json_download": "/v1/jobs/<id>/download?format=json",
    "okf_bundle_download": "/v1/jobs/<id>/download?format=okf_bundle"
  },
  "metadata": {
    "okf": {
      "status": "generated",
      "okf_version": "0.1",
      "evidence_anchoring": "bound"
    }
  }
}

Download the bundle

bash

curl -L "https://api.docushell.com/api/v1/jobs/<id>/download?format=okf_bundle" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o acme-q3-earnings.okf.zip
The artifact is a .okf.zip you can unzip, commit to git, or feed straight into a knowledge tool.

Schema

Document Frontmatter

Every concept document begins with a YAML frontmatter block. type is the only required key; the rest are DocuShell extensions that make the bundle queryable.

FieldMeaning
typeConcept kind — Parsed Document or Source Document.
titleHuman-readable display name derived from the file.
descriptionOne-line summary used by indexes and previews.
source_fingerprintSHA-256 fingerprint of the source file (sha256:…).
pagesNumber of pages parsed into the concept.
evidence_anchoringEthos verdict: bound, unverified, skipped, or failed.
okf_producerAlways docushell/parse-pdf for DocuShell-generated bundles.

Trust

Source-Anchored Citations

OKF bundles from DocuShell are anchored, not just converted.

Anyone can convert a PDF to Markdown. DocuShell goes further: the Ethos layer checks parser evidence refs against the source document fingerprint, and records the outcome in every bundle. A consuming agent can tell verified knowledge from a guess.

The # Citations section of the document concept links back to references/source.md, which carries the fingerprint and the per-document anchoring verdict. When anchoring fully succeeds, the frontmatter reports evidence_anchoring: bound.

  • source_fingerprint content-addresses the exact file every concept came from.
  • evidence_anchoring reports the per-document verdict in frontmatter.
  • Bundles never claim verified status when one or more passages fail to bind.

Openness

Conformance And Portability

DocuShell emits OKF v0.1 conformant bundles: every concept document has a parseable frontmatter block with a non-empty type, and reserved index.md / log.md files follow the spec. Because the format is open and dependency-free, you are never locked into DocuShell to read what you generated.

  • Open spec, Apache 2.0 — the format carries no vendor dependency.
  • Consume bundles with cat, Obsidian, Notion, MkDocs, or any Markdown viewer.
  • Ingest into compatible knowledge catalogs or any system that reads files.

OKF specification

The official Open Knowledge Format v0.1 spec.

Parse PDF reference

The base endpoint and all parse options.