H2C vs JSON vs YAML vs Natural Language

Q: Does H2C use fewer tokens than JSON or natural language?

Not in the published reference benchmarks. H2C uses more tokens in those scenarios because it carries explicit state. Its goal is structured, checkable handoffs rather than token reduction.

Compare how H2C, JSON, YAML and prose represent an AI agent handoff, including revisions and workflow 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 uses quotes, braces and commas to represent data. It does not define agent workflow state by itself.

❌

LLM Hallucination Risk

Generated JSON can contain syntax errors, such as a missing comma or brace. H2C also has a grammar; validate either format before relying on its output.

📋

No Agent Semantics

JSON does not define versioning, cycle tracking or context management. Applications can add those conventions to their own schemas.

Why Not YAML?

📏

Whitespace Sensitivity

YAML uses indentation to express structure. H2C uses typed blocks and explicit delimiters instead.

⚠️

Norway Problem

YAML parsers may interpret plain values according to schema and version rules. Check the parser behavior when values such as no matter.

🐌

Slow for LLMs

YAML parsing depends on indentation. H2C uses explicit delimiters, but both formats still need a parser to validate structure.

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 defines workflow fields such as cycle ids and revisions. JSON and YAML can represent the same data when an application defines a schema.

Handoff Format FAQ

Does H2C use fewer tokens than JSON or natural language?

No. The published reference benchmarks use more tokens for H2C in the measured scenarios because it carries explicit state. H2C focuses on structured, checkable handoffs, not token reduction.

When should I use H2C instead of JSON or YAML?

Consider H2C when an agent workflow needs explicit block types, revisions, cycle tracking or context-management commands. JSON and YAML may be a better fit for general-purpose data exchange.

Do I need an H2C library?

No. H2C is plain text and can be written without an SDK or runtime. A reference parser and validator are available in the project repository.

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