# 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.

Source: https://docs.docushell.com/okf
Category: Reference
Read time: 8 min

## Related

- [Parse PDF](/parse-pdf.md): Review the base parse endpoint OKF rides on.
- [Enable OKF](#okf-request): Add okf=true and download the .okf.zip bundle.
- [Evidence anchoring](#okf-anchoring): See how source anchoring is recorded in the bundle.

## Summary

| Label | Value | Description |
| --- | --- | --- |
| 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. |

## 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.

## 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.

## 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.

## 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.

| Field | Meaning |
| --- | --- |
| type | Concept kind — `Parsed Document` or `Source Document`. |
| title | Human-readable display name derived from the file. |
| description | One-line summary used by indexes and previews. |
| source_fingerprint | SHA-256 fingerprint of the source file (`sha256:…`). |
| pages | Number of pages parsed into the concept. |
| evidence_anchoring | Ethos verdict: `bound`, `unverified`, `skipped`, or `failed`. |
| okf_producer | Always `docushell/parse-pdf` for DocuShell-generated bundles. |

## 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.

## 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.

### Quick Links

- [OKF specification](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md): The official Open Knowledge Format v0.1 spec.
- [Parse PDF reference](/parse-pdf.md): The base endpoint and all parse options.