H2C vs JSON vs YAML vs Natural Language

Why general-purpose formats fall short for AI-to-AI communication — and how H2C solves it with 83–96% token savings.

Format Comparison Matrix

Feature	H2C	JSON	YAML	Natural Language
Token Efficiency	83–96%	~40%	~45%	Baseline (0%)
LLM Parse Reliability	High	Medium	Medium-Low	N/A
Context Management	Built-in	None	None	None
Version Tracking	Built-in (rev:)	Manual	Manual	Manual
Cycle Tracking	Built-in (cycle:)	None	None	None
Self-Describing	Yes	No	Partial	No
Zero-Shot Cross-Model	4/4 families	3/4 families	2/4 families	Varies
Chain Length Support	130+ msgs	~60 msgs	~50 msgs	~40 msgs
Schema Required	No	Recommended	Optional	No
Whitespace Sensitive	No	No	Yes	No

Why Not JSON?

{ }

Syntactic Overhead

JSON requires quotes, braces, and commas that consume tokens without adding semantic value. A typical agent handoff in JSON uses 2–3x more tokens than the equivalent H2C block.

❌

LLM Hallucination Risk

LLMs frequently produce malformed JSON: missing commas, unclosed braces, or trailing commas. H2C's simpler grammar reduces parse errors to near zero.

📋

No Agent Semantics

JSON carries no built-in semantics for versioning, cycle tracking, or context management. Every framework must invent its own conventions on top.

Why Not YAML?

📏

Whitespace Sensitivity

YAML's indentation-based structure is a frequent source of LLM errors. A single space off breaks the entire document. H2C uses explicit delimiters.

⚠️

Norway Problem

YAML's type coercion (e.g., no → false, country codes breaking) is a known footgun. H2C has no implicit type conversion.

🐌

Slow for LLMs

LLMs generate YAML ~30% slower than H2C due to indentation tracking overhead. Every line requires the model to count spaces correctly.

Same Information, Different Formats

❌ Natural Language (~180 tokens)

I've set up a new FastAPI weather service
using Python 3.11. The service includes
multiple endpoints for weather data fetching
with caching (10 minute TTL) and rate limiting
at 60 requests per minute. I've structured
the code with separate routers and service
layers. Authentication is handled via API key
stored in environment variables...

✅ H2C (~55 tokens)

[ARCH:PLAN]
id:weather-api|fw:python3.11
lib:[fastapi,httpx,cachetools]
auth:APIKey::env(OPENWEATHER_API_KEY)
struct:[main.py,routers/,services/]
notes:[cache_TTL_10min,rate-limit_60req-min]

⚠️ JSON (~120 tokens)

{
  "type": "architecture_plan",
  "id": "weather-api",
  "framework": "python3.11",
  "libraries": ["fastapi", "httpx", "cachetools"],
  "auth": {"type": "APIKey", "env": "OPENWEATHER_API_KEY"},
  "structure": ["main.py", "routers/", "services/"],
  "notes": ["cache TTL: 10min", "rate-limit: 60/min"]
}

⚠️ YAML (~95 tokens)

type: architecture_plan
id: weather-api
framework: python3.11
libraries:
  - fastapi
  - httpx
  - cachetools
auth:
  type: APIKey
  env: OPENWEATHER_API_KEY
structure:
  - main.py
  - routers/
  - services/
notes:
  - cache TTL: 10min
  - rate-limit: 60/min

H2C uses 55 tokens vs 180 (NL), 120 (JSON), 95 (YAML) — and includes built-in semantics none of the others provide.

H2C Is Purpose-Built for AI Agents

JSON and YAML are data formats. H2C is an agent communication protocol. The difference matters at scale.

Read the Spec See Examples