What is YON?

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."

Four Pillars

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 |

Specification

Chapters (Normative)

| # | 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 |

Grammar

| Document | Format | | ----------------------------------------- | --------- | | Grammar | Annotated | | Grammar EBNF | Raw EBNF |

Reference

| 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 |

Reading Paths

| 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 |

Guides (Informative)

| 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 |

Conformance

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.

Governance

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 |

Domains

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.

The YON Toolchain

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 |

The YON Project

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).

About YounndAI

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.

License & Attribution

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

| | | | ------------- | ------------------------------------------------------------------ | | Spec | YON v2.0 | | Author | Alexandru Mareș | | Company | MARLINK TRADING SRL · YounndAI™ | | License | Apache 2.0 — © 2026 MARLINK TRADING SRL | | Trademark | YounndAI™ Trademark Guidelines |