H2C vs JSON vs YAML vs Natural Language

Why general-purpose formats fall short for agent handoffs — and what H2C adds: typed blocks, fix cycles, versioned state.

Format Comparison Matrix

Feature	H2C	JSON	YAML	Natural Language
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
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.

❌

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

Indentation tracking adds parsing overhead absent in H2C's explicit delimiters. Every line requires the model to count spaces correctly.

Same Information, Different Formats

❌ Natural Language

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

[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

{
  "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

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 adds built-in semantics — cycle ids, revisions, validated state — that JSON and YAML leave to convention.

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