MeDF — Mutable Expression Description Format: immutable hashed text blocks with mutable presentation
maskin7 min read

MeDF: Making Documents Verifiable Without Trust, Servers, or Blockchains

MeDF (Mutable Expression Description Format) fixes a document's state — proving what text existed, when, and with what intent — with immutable hashed blocks and free-form presentation. It works offline, with no trust authority or blockchain. Plus MeDF Hub, the platform built on it.

The problem: we can format documents, but we can't fix their state

We have endless ways to *present* a document — HTML, PDF, Markdown, slides — but almost no lightweight way to say, with certainty: *"this exact text existed, at this point in time, with this intent."* When a policy, a research paper, or an AI-generated report changes, how do you prove which words were actually there before?

MeDF (Mutable Expression Description Format) is a small, open format that answers exactly that question — and nothing more. It makes text verifiable while leaving presentation completely free. It works fully offline, and it requires no servers, no trust authority, and no blockchain.

MeDF's own summary puts it bluntly: it is *"a format to fix document states, not to judge correctness or authority."*

---

The core idea: immutable text, mutable presentation

MeDF draws one clean line through a document:

  • Immutable — the *text content*. This is hashed and becomes part of the document's cryptographic identity.
  • Mutable — *everything else*: rendering (HTML/PDF), layout, styling, table of contents, indexing, interpretation.
+---------------------------+
|        MEDF Document      |
+---------------------------+
|  Immutable Text Blocks    |  ← hashed & verifiable
|  block: executive_summary |
|  block: policy            |
|  block: appendix          |
+---------------------------+
|  Mutable Presentation     |  ← free to change
|  rendering (HTML/PDF)      |
|  indexing / TOC           |
|  layout / styling         |
+---------------------------+

Only the text blocks are part of the identity. You can restyle, re-render, or re-index a document forever without ever breaking its verification.

---

How it works

A MeDF document is just a JSON file. Text is split into blocks — minimal semantic units — each with a stable block_id and its own block_hash. The whole document then gets a single doc_hash.

{
  "medf_version": "0.2.1",
  "id": "document-id",
  "snapshot": "2026-02-05T10:00:00Z",
  "issuer": "issuer-code",
  "blocks": [
    {
      "block_id": "introduction",
      "role": "body",
      "format": "markdown",
      "text": "...",
      "block_hash": "sha256:..."
    }
  ],
  "doc_hash": { "algorithm": "sha-256", "value": "..." }
}

Three design choices make this robust and interoperable:

  1. SHA-256, hash-first, signature-optional. Hashing is the baseline; cryptographic signatures (ed25519) are an optional add-on for "who fixed this state," never a requirement.
  2. RFC 8785 (JSON Canonicalization Scheme). MeDF deliberately does *not* invent its own canonicalization rules. It reuses the JCS standard so hashes are reproducible with off-the-shelf crypto tooling.
  3. Markdown as semantic content. blocks[].text uses Markdown as *meaning*, not styling — so it counts as part of the verifiable content, while visual rendering stays out of scope.

---

The workflow

The reference implementation is a single Python CLI:

python3 medf.py init > document.medf.json      # create a skeleton
python3 medf.py import paper.md                 # convert Markdown → MeDF (auto-packs)
python3 medf.py pack document.medf.json         # generate block + doc hashes
python3 medf.py verify document.medf.json       # verify integrity, offline
python3 medf.py sign document.medf.json --key private.key   # optional signature
python3 medf.py explain                          # explain the verification philosophy

Two features make MeDF genuinely useful in practice:

Block-level diff. Instead of noisy line diffs, MeDF compares documents semantically:

Block changed:   policy
- Previous hash: sha256:ab12...
+ New hash:      sha256:ff98...
Block unchanged: executive_summary
Block added:     appendix

A --json flag makes this CI-friendly — and the repo ships a GitHub Actions workflow that auto-verifies every *.medf.json on push.

Precise citation. You can cite a *specific block*, not just a document:

MEDF: paper-2026-example#methodology

---

What MeDF is deliberately *not*

This is the part people most often get wrong, so the project is emphatic about it. MeDF is not a blockchain, not a trust or identity system, not a certificate authority, and not a content-moderation tool. It does not judge whether content is correct, decide who should be trusted, or prevent anyone from publishing falsehoods.

MeDF only:

  • makes text content verifiable,
  • detects unintended or malicious changes,
  • enables precise, block-level references.

The philosophy behind it is consistent: a hash is a responsibility boundary, not a badge of legitimacy. It proves "unchanged from this state" — not "true," not "official," not "trustworthy." History is modeled as chains (each state links to a previous), branching is allowed, and there is no privileged "official" timeline. Trust and key management are intentionally left outside the core spec.

On the increasingly urgent question of AI-generated documents, MeDF takes a refreshingly clear stance:

"The problem is not 'AI wrote this' — the essence is 'provenance and responsibility cannot be verified.'"

MeDF provides verifiable state regardless of whether a human or a model produced the text.

---

MeDF Hub: the format, turned into a platform

Where the medf repository is the format and CLI, **MeDF Hub** (live demo) is a full web platform built on the v0.2.1 spec — a place to share, verify, and discuss documents block by block, with tamper-resistance and decentralized publishing via IPFS.

Its feature set shows what the format enables in production:

  • Documents — GitHub-Flavored Markdown auto-split into blocks, RFC 8785 + SHA-256 verification (in-browser via the Web Crypto API), version history with diffs and rollback.
  • Discussion — comments attached to *specific blocks*, threaded replies, and automatic detection/linking of MeDF citations with bidirectional reference tracking.
  • IPFS — SHA-256-based CID generation and one-click publishing to the IPFS network via Pinata, with public gateway access.
  • Export — HTML (with metadata, TOC, hash display), PDF, and raw MeDF JSON.

Under the hood it runs React 19 + Tailwind 4 on the client, Express 4 + tRPC 11 on the server, MySQL/TiDB for storage, and Pinata for IPFS — with a data model centered on documents, blocks, comments, references, and document_versions.

---

Why it matters

MeDF is a small idea with a wide reach. By refusing to solve trust, authority, or correctness, it stays simple enough to be durable — a plain JSON file, verifiable with standard tools, decades from now, with no server to outlive it. For researchers who need citable, tamper-evident text; for organizations tracking policy revisions; and for a world flooded with machine-generated content that no one can trace — being able to prove *what existed, when, and with what intent* is quietly foundational.

  • Format & CLI: https://github.com/maskin/medf (MIT)
  • Platform: https://github.com/maskin/medf-hub · https://medf-hub.vercel.app

---

日本語まとめ：MeDF とは何か

MeDF（Mutable Expression Description Format） は、文書の「正しさ」や「権威」を判定するのではなく、「ある文書が、いつ、誰の意図で、どんな状態で存在したか」を固定するためのオープンな文書フォーマットです。サーバー・信頼機関・ブロックチェーンを必要とせず、完全にオフラインで検証できます。

中心となる考え方：テキストは不変、表現は可変

  • 不変（immutable） … テキスト本文。ハッシュ化され、文書の暗号学的な同一性の一部になります。
  • 可変（mutable） … レンダリング（HTML/PDF）、レイアウト、目次、索引、解釈など、それ以外すべて。

本文だけが同一性の一部なので、再スタイリング・再描画・再索引をいくら行っても検証は壊れません。

仕組み

文書は JSON ファイルです。テキストを最小意味単位のブロックに分割し、各ブロックに block_hash、文書全体に doc_hash を付与します。設計上のポイントは次の3つ:

  1. SHA-256・ハッシュ優先・署名は任意（ed25519 署名は「誰が固定したか」を示す追加要素）。
  2. RFC 8785（JSON 正規化）を採用 — 独自ルールを作らず、既存の暗号ツールと相互運用可能。
  3. Markdown は意味づけ — 見た目ではなく検証対象の内容として扱う。

できること

  • medf.py の CLI で init / import / pack / verify / sign / diff / explain。
  • ブロック単位の差分（行単位ではなく意味単位）と、MEDF: 文書ID#ブロックID 形式の精密な引用。
  • GitHub Actions で *.medf.json を push 時に自動検証。

あえて「やらないこと」

MeDF はブロックチェーンでも、信頼・認証基盤でも、認証局でも、モデレーションツールでもありません。内容の正誤を判定せず、誰を信頼すべきかも決めず、虚偽の公開も止めません。 ハッシュは「正しさ」ではなく「この状態から変わっていない」という責任の境界を示すだけです。AI 生成文書についても「AI が書いたこと」ではなく「来歴と責任が検証できないこと」が本質だと位置づけています。

MeDF Hub — フォーマットをプラットフォームへ

**MeDF Hub**（デモ）は、v0.2.1 仕様に準拠した文書共有・議論プラットフォームです。Markdown のブロック分割・ブラウザ内検証、ブロック単位のコメントとスレッド議論、参照の双方向トラッキング、IPFS 公開（Pinata 連携）、HTML/PDF/JSON エクスポートを備え、React 19 + Express/tRPC + MySQL/TiDB で構築されています。

正しさ・権威・信頼をあえて扱わないことで、MeDF は「標準ツールだけで、何十年後でも検証できる一枚の JSON」という耐久性を手に入れています。機械生成コンテンツが溢れる時代に、「何が・いつ・どんな意図で存在したか」を証明できることは、静かで、しかし基盤的な価値です。

  • フォーマット & CLI: https://github.com/maskin/medf （MIT）
  • プラットフォーム: https://github.com/maskin/medf-hub · https://medf-hub.vercel.app

Continue reading