Schema

Domain Schema Format

A domain is a typed schema that defines an industry's structured data. Each domain contains tags — named record types with typed fields, validation rules, and trust signals. Domain Schemas are 100% agonstic JSON payloads. They represent the ultimate source of truth for structured data validation.

You do NOT need to use YounndAI Object Notation (YON) to benefit from domains. YON is simply one consumer type. Any parser, application, or AI agent that consumes JSON can fetch a schema from the registry and instantly enforce strong types, validation, and domain-awareness across their workflow.

Three Payloads

Each domain serves three distinct payloads. This separation is intentional: parsers need lean schemas for validation, while humans and AI agents benefit from rich metadata.

Schema

Validation & Trust

The default response. Contains typed records with fields, validation rules, and trust signals. Lean and cacheable — exactly what parsers need.

~1–5 KBCache: Long TTL

GET /api/domains/yon.health

Metadata

Rich Context

Human and AI-readable context beyond validation: taglines, use cases, field labels with units, related standards, cross-domain links, and conformance metrics.

~5–15 KBCache: Separate

GET /api/domains/yon.health?include=metadata

Registry

Ownership & Lifecycle

Namespace and domain ownership, operational states, and lifecycle data. Namespace and domain carry independent states — owner transfers don't affect schemas.

~1–3 KBCache: Separate

GET /api/domains/yon.health?include=registry

Agnostic JSON Usage

Domain schemas are universal and framework-agnostic. The @younndai/domains (or yai-domains) package provides plug-and-play parsing to apply these schemas over any JSON payload.

Discover schemas

Browse the registry or search by industry. Each domain has a unique path like yon.health or stripe.payments.

Fetch the schema

GET /api/domains/{path} returns the lean schema payload: tags, fields, types, and validation rules.

Validate structured data

Use the tags and fields to validate incoming data. Each field has a type, required flag, and optional pattern/range/enum constraints.

Enrich with metadata

Add ?include=metadata to get rich context: use cases, field labels, units, related standards, and cross-domain relationships.

How YounndAI Object Notation Uses Domains

The YounndAI Object Notation (YON) specification uses domains as its schema registry. Here's how the parser and generator interact with domains.

Infographic Placeholder 2

The JSON Consumer vs YON Parser

Design Prompt: Agnostic pipeline diagram. Top path: Any generic JSON client calling GET /api/... to receive pure JSON. Bottom path: The YON Parser pulling the same domain schema to validate tags. Thematic message: The schema is universal.

Infographic Placeholder 3

Schema Hierarchy & Structure

Design Prompt: A technical Bento-style tree graph showing the relationship: Domain -> contains Records -> contains Fields. Emphasize the structured nature of the data.

Parser fetches the schema

When a YON document declares @DOC domain=yon.health, the parser fetches the schema payload to discover valid tags and their typed fields. Official yon.* schemas ship bundled with the parser — no network call needed.

Tags define the vocabulary

Each tag in the schema (VITALS, DX, PRESCRIPTION) becomes a valid record type. The parser validates that documents only use tags defined in their domain, with correctly typed fields.

AI agents request metadata

When an AI agent needs deeper context — what does the 'bp' field mean? What unit? What's a typical value? — it requests ?include=metadata. The metadata payload provides human-readable labels, units, examples, related standards, and use cases.

Generator structures output

The YON generator uses domain schemas to produce correctly structured output. It knows which tags exist, what fields each tag requires, and what types and constraints to enforce.

Schema Reference

● Required○ Optional

Top-level fields returned in the schema payload.

Top-Level Schema Object

Field

Type

Description / Constraints

●

$schema

string

JSON Schema reference URL

●

description

string

Human-readable description of the domain

●

domain

string

Fully qualified domain path

e.g. yon.health

●

version

string

Semantic version

e.g. 2.1

●

status

string

Lifecycle state

pendingactivedeprecatedarchivedrevoked

e.g. active

●

tier

string

Trust tier

communityinstitutionalpartnerofficial

●

verified

boolean

Identity + quality trust gate

●

score

float

Conformance confidence

e.g. 0.0–1.0

○

schemaHash

string

SHA-256 hash of the schema payload

○

defaultMode

string

Default YON parsing mode (e.g. 'strict', 'loose')

○

defaultProfile

string

Default YON profile (e.g. 'core', 'chat')

○

defaultFormat

string

Default YON output format (e.g. 'min', 'pretty')

●

notice

string

Highest-severity notice code, or null

●

records

array

Record type definitions with typed fields

Record Definition

Each entry in the records array

Field

Type

Description / Constraints

●

tag

string

Tag name without @

e.g. VITALS

○

description

string

Human-readable description

●

fields

array

Typed field definitions

Field Definition

Each entry in a record's fields array

Field

Type

Description / Constraints

●

name

string

Field name

e.g. temperature

●

type

string

Official YON AST Data type

strintfloatbooltsbytesrefstreamvector

○

required

boolean

Is field mandatory?

○

description

string

Human-readable description

○

pattern

string

Regex for string validation

e.g. ^[A-Z]{2}$

○

range

array

Numeric bounds [min, max]

e.g. [0, 300]

○

enum

array

Allowed values list

Trust Signals

Every schema carries four trust signals for AI agents: tier (who published) + verified (identity confirmed) + score (quality gate) + notice (operational health).

Official✦ YON OfficialMaintained by YounndAI — score: 1.0

Institutional✓ YON VerifiedVerified institution, Gold+ conformance

Partner✓ YON VerifiedIdentity verified, Gold+ conformance

Community○ CommunitySelf-published, no review

Registry API

The YounndAI Domains Registry serves domain schemas via REST API at domains.younndai.com.

Endpoint

Returns

Cache

GET /api/domainsList of all domains5 min

GET /api/domains?tier=officialFilter by tier5 min

GET /api/domains/search?q=healthFull-text search domains1 min

GET /api/domains/statsGlobal registry statistics5 min

GET /api/domains?namespace=stripeFilter by namespace5 min

GET /api/namespacesList all namespace claims5 min

GET /api/namespaces/stripeNamespace details & owner5 min

GET /api/domains/yon.healthSchema payload (lean)1 hour

GET /api/domains/yon.health?include=metadataSchema + metadata1 hour

GET /api/domains/yon.health?include=registrySchema + registry1 hour

GET /api/domains/yon.health?include=allAll payloads1 hour

GET /api/domains/yon.health?version=2.1Schema at specific versionImmutable

GET /api/domains/yon.health/versionsAll versions with status5 min

GET /api/noticesGlobal registry notices5 min

GET /api/announcementsSystem announcements1 hour

GET /api/healthAPI service health checkNone

Parser Cache Strategy

Parsers resolve domains through a three-tier cache hierarchy.

Infographic Placeholder 4

The 3-Tier Cache Strategy

Design Prompt: A cascading execution flow. Tier 1 (Bundled) hits immediately in 0ms. Tier 2 (Cached) hits memory. Tier 3 (Live Network) fetches from API. Emphasize speed and reliability.

Bundled

Official yon.* schemas ship with the parser

Network: Never

Cached

Previously fetched schemas stored locally with TTL

Network: On miss

Live

Fetched from registry API on demand

Network: Yes

Cache Rules

24-hour TTL for latest resolution, infinite for pinned versions
Use ETag / If-None-Match for efficient revalidation (304 Not Modified)
Graceful degradation: if registry unreachable, continue with WARN
Offline mode: parsers function fully offline using only bundled schemas

Ready to explore?

Browse published domain schemas in the registry, or check out the pricing model for publishing your own.

Explore Domains View Pricing