YON — YounndAI Object Notation™
Stream-first data format for AI agent workflows
One malformed line costs one line, not the whole document.
Data, intent, provenance, and thought — in one stream.
Quick Start · Apache 2.0 · Trademark Policy · Brand Assets
YON is not a JSON replacement — different category, different job. Transport formats move data between machines; YON fills the gap between prose and markdown — readable but unstructured — and those transport formats — structured but carrying data alone. It is structured and parseable, line-oriented, designed for both human and AI consumption, and it holds what neither was built for: data, intent, provenance, and thought, in one stream. Structure carries the meaning, not just the data. Every record line is independently parseable. No global schema required. Enter mid-stream and understand.
The same format — with no code and no schema changes — serves as a data container, a prompt, a configuration file, an execution plan, a chain of thought, a provenance record, or a multi-agent controller. The tag system provides the semantics. Domains provide the vocabulary. The format encodes what the emitter said — it does not decide what the emitter meant. See The Case for YON for the full engineering justification.
@DOC ver=2.0 | id=hello | title="Hello World"
@INTENT goal="Demonstrate YON basics"
@RULE lvl=MUST | when="any output" | then="be valid YON v2.0"
@NOTE text="Every line stands alone. That's the point."
Every YON document can carry four kinds of information:
| Pillar | What it captures | Example Tags |
|---|---|---|
| Data | What IS — structured facts | @DOC, @SEC, @NOTE |
| Intent | What it WILL DO — constraints | @INTENT, @RULE |
| Provenance | What HAPPENED — audit trail | @STAMP |
| Thought | What it THINKS — reasoning | @THOUGHT, @DECISION |
| # | Chapter | Content |
|---|---|---|
| 1 | Introduction | Vision, principles, quick example |
| 2 | Core Language | Records, types, blocks, references |
| 3 | Document Model | Sections, metadata, privacy |
| 4 | Modes | Modes, profiles, formats |
| 5 | Workflow | Steps, error handling, streaming |
| 6 | Cognition | Thinking, perception, memory, affect |
| 7 | Agents | Dialogue, streams, collaboration |
| 8 | Execution | Runner model, permissions, sandbox |
| 9 | Operations | Standard Library (YSL) — 75 operations |
| 10 | Transport | HTTP, SSE, WebSocket, Stdio |
| Document | Format |
|---|---|
| Grammar | Annotated |
| Grammar EBNF | Raw EBNF |
| Document | Content |
|---|---|
| Tag Registry | Complete tag catalog |
| Error Codes | E001–E006, E101–E112 |
| Type System | 9 built-in types |
| Common Fields | Shared field patterns |
| Glossary | Term definitions |
| I am a... | Start here | Then read |
|---|---|---|
| New to YON | Quick Start | → Introduction → Core Language |
| Backend engineer | Records → Transport → Operations | → Execution → Workflow |
| AI engineer | Cognition → Agents → Execution | → Brain Architecture → Operations |
| Domain specialist | Domains Overview → Schema Format | → Cross-Domain Guide → Modes |
| LLM developer | LLM Guide → Modes → Core Language | → Grammar |
| Guide | For |
|---|---|
| Quick Start | Everyone — 5 min to YON |
| LLM Guide | LLM developers |
| LLM Card | Compact guide for LLMs |
| LLM Read Card | Reading YON (for LLMs) |
| LLM Write Card | Writing YON (for LLMs) |
| LLM Domains Card | Domains (for LLMs) |
| Cross-Domain | Domain specialists |
| Transport Patterns | Backend engineers |
| Brain Architecture | AI engineers |
| Rationale | Why YON exists |
| Limitations | Where YON loses — and what to use instead |
| Annex | Pronunciation, naming |
The official YON Conformance Test Suite contains 149 vectors (116 parser + 33 runner) covering syntax, profiles, errors, domains, security, streaming, agent runtime, and cognition runtime. See conformance/ for the full suite and vector catalog.
Trust is infrastructure. These policy documents define how the specification is maintained, extended, and protected:
| Document | Purpose |
|---|---|
| Normative Tiers | Stability guarantees |
| Versioning | Domain lifecycle |
| Namespace Registry | Tier model, namespaces |
| RFC Process | Proposal lifecycle |
| Conformance | Implementation levels |
| TRADEMARK | Trademark guidelines and enforcement |
| CERTIFICATION | Implementation certification program |
| REGISTRY | Domain registration and verification |
| CLA | Contributor License Agreement |
| SECURITY | Vulnerability reporting and response |
YON includes 34 official domains — industry-specific record types covering healthcare, fintech, aerospace, maritime, pharma, construction, environmental, transportation, hospitality, and more. Domain reference docs remain here; schema JSON and the master index ship from @younndai/domains.
| Document | Content |
|---|---|
| Overview | What domains are |
| Schema Format | JSON schema structure |
| Registry | Official domain list |
Domains are independently versioned and governed through the four-tier namespace model: Community → Institutional → Partner → Official. See Versioning for details.
Open-source packages that bring the specification to life — reference implementations plus companions:
| Package | Role | Purpose | License |
|---|---|---|---|
@younndai/yon-parser |
Reference implementation | Parse YON → AST, validate, format | Apache 2.0 |
@younndai/yon-runner |
Reference implementation | Execute YON workflow documents | Apache 2.0 |
@younndai/yon-generator |
Reference implementation | Build valid YON documents from code | Apache 2.0 |
@younndai/yon-converter |
Reference implementation | Convert YON ↔ JSON/YAML/TOML/XML/CSV/INI | Apache 2.0 |
@younndai/yon-benchmarks |
Companion | Quantitative evidence for the format | Apache 2.0 |
@younndai/yon-examples |
Companion | Runnable cookbook | Apache 2.0 |
@younndai/domains |
Companion | YounndAI Domain schemas + validation | Apache 2.0 |
@younndai/ai-relay |
Companion | Provider-agnostic LLM gateway | Apache 2.0 |
YON is an open block format and toolchain.
- Specification —
@younndai/yon-spec— this repository: the normative YON v2.0 standard. - Toolchain —
YounndAI/yon— parser, generator, runner, converter, examples, benchmarks, domains, ai-relay. - Editor support —
yon-vscode(VS Code Marketplace) ·@younndai/yon-textmate(TextMate grammar).
YounndAI™ — You and AI, unified. (pronounced "yoon-dye")
A philosophy of intelligence: building with intention, so humans and machines think together without losing what makes either whole.
Apache-2.0. © 2026 MARLINK TRADING SRL (YounndAI). See LICENSE and NOTICE.
"YON" and "YounndAI" are trademarks of MARLINK TRADING SRL — see TRADEMARK.md and the Trademark Policy.
Specification created by Alexandru Mareș.
Website: yon.younndai.com
Structure before scale. Harmony above all.
| Spec | YON v2.0 |
| Author | Alexandru Mareș |
| Company | MARLINK TRADING SRL · YounndAI™ |
| License | Apache 2.0 — © 2026 MARLINK TRADING SRL |
| Trademark | YounndAI™ Trademark Guidelines |