ADR-0006: JSON Canonical Format for Specs
Accepted
Date: 2026-06-10
Context
The platform’s structured artifacts (Manifests, Archetype Specs, Capability and Contract registry entries) need a canonical serialization format. The choice is between JSON, YAML, TOML, and various binary formats. JSON and YAML are the realistic contenders.
JSON is machine-friendly, unambiguous, well-supported in every language, and validates cleanly against JSON Schema. YAML is more readable for nested structures and common in DevOps workflows. Both lose-losslessly convert to each other.
Decision
JSON is the canonical format. JSON Schema is used for validation. YAML is an acceptable edit-time format and converts to JSON before storage.
Rationale
- JSON has unambiguous parsing rules; YAML has well-known parsing pitfalls (Norway problem, version-string coercion).
- JSON Schema is the standard validation language and is broadly tooled.
- Most platform internals already process JSON natively.
- Allowing YAML as an authoring format gives users the readability benefit without the canonical-storage ambiguity.
Consequences
- All schemas (Adapter Manifest, Module Manifest, Archetype Spec) are defined as JSON Schema.
- Internal storage, audit logs, and inter-service communication use JSON.
- Documentation may show examples in YAML for readability when nested structure benefits from it.
- Conversion utilities between JSON and YAML are part of the platform tooling.