How It Works
Schema resolution, versioning, and the four payloads of YounndAI Domains.
Resolution Flow
When a consumer requests a domain, the registry resolves it through a deterministic path:
Parse the identifier
yon.health splits into namespace yon and domain health
Locate in registry
The registry checks its index for the matching entry
Version resolution
If no version is specified, latest is served. Otherwise, the pinned version is returned.
Serve schema
The full domain schema is returned as JSON
GET /api/domains/yon.health
{
"domain": "yon.health",
"version": "1.0",
"status": "active",
"description": "Healthcare domain covering patient data and clinical records",
"records": [...]
}The Four Payloads
Every domain request can return one of four payload shapes via the include parameter:
The full domain definition — records, fields, validation rules. This is what consumers use to integrate.
Rich context beyond validation — taglines, use cases, per-tag field descriptions, and external resource links. Useful for UI display and AI agent understanding.
GET /api/domains/yon.health?include=metadata
{
"meta": {
"tagline": "Clinical decision support for AI-powered healthcare",
"highlights": ["VITALS", "DX", "RX"],
"tag_context": { ... }
}
}Ownership, namespace details, and operational lifecycle data — publisher, tier, verification status, and notice codes.
All three payloads merged into a single response. Use ?include=all to get schema + metadata + registry in one request.
Immutable Versioning
Published versions are locked via content hash. The same version identifier always returns the same schema:
⚠️Warning
Once published, a domain version cannot be modified. Bug fixes and enhancements require a new version number. This guarantees consumers always get exactly what they pinned to.
- Minor (
1.1) — New optional fields, new tags, metadata corrections - Major (
2.0) — Removed fields, type changes, renamed tags