UFN — USE Frame Notation

Status of This Memo

This document specifies a Standards Track notation for the kova ecosystem and requests discussion and suggestions for improvements. UFN v2 is the current, stable (locked) revision. It generalizes the original game-frame profile (UFN v1, see Section 10) into a domain-agnostic, nesting-capable wire format for the agent edge.

Distribution of this memo is unlimited. The notation is published openly: UFN is a frame, not a moat — it carries no proprietary semantics of its own.

Abstract

UFN (USE Frame Notation) is a one-line, dictionary-driven notation for structured output produced by Large Language Models. Where JSON spends a per-token tax on { } [ ] " , on every structured reply, UFN moves structure into named, self-delimiting tags and a tight separator, so a model spends its tokens on content, recovers cleanly from truncation, and streams its header before its prose.

UFN is intended for the edge between a model and a consumer — not for storage. Storage stays JSON; UFN is the token-economical wire format an LLM emits and a parser ingests. On a representative task list it is approximately 59% smaller than compact JSON on the structural portion, raises parse-failure-on-truncation from JSON's total loss to a usable partial frame, and cuts time-to-first-content from tens of seconds to roughly 1.5 seconds by streaming the header ahead of the prose.

Copyright Notice

Copyright © 2026 Kovanex / I. Podtsebnev. This specification is licensed under the Apache License, Version 2.0. Implementations are unrestricted.

Table of Contents

1.Introduction

UFN is the smallest legal notation that gives a producer tagged records plus a free prose tail on a single line. It is what git log --pretty and mail headers do, conceptually: a tight set of keyed records, no nesting ceremony, robust to a line that gets cut short. The conceptual model is 1990s SMS / ICQ / IRC compression — sender and receiver share a tiny convention dictionary, every byte counts, and a partial message still makes sense.

1.1.Motivation

JSON was the obvious first choice for LLM structured output: models are well trained on it and every language ships a parser. In production over local models, three costs become visible:

• Token tax on syntax. A four-field header can cost ~110 tokens in JSON against ~38 in UFN — 30–65% of a short reply spent on braces, quotes, and commas rather than content. On constrained hardware that is wall-clock the user waits through.
• Truncation equals total failure. A single missing } makes the whole reply unparseable. Measured: ~20% of benchmark runs hit the fallback path purely because a brace was missing — not because the model broke character.
• Hostile to streaming. JSON closes at the end; nothing can render until the last bracket balances. The consumer stares at a blank screen for the full generation.

1.2.Requirements Language

The key words MUST, MUST NOT, REQUIRED, SHALL, SHOULD, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in BCP 14 (RFC 2119) when, and only when, they appear in all capitals.

1.3.Design Scope

2.Notation Model

Everything is one line, ;-separated. A token is classified by its shape alone — there are exactly three kinds:

2.2.Fields

A field is key:value. The key MUST come from the shared dictionary; the value is free text up to the next field separator. The field separator is ; (tight, no surrounding spaces) at the general edge. (The v1 game profile uses ; with surrounding spaces; see Section 10.)

2.3.Scopes and Nesting

A bare token that is not a field and does not start with / opens a scope; a bare / closes the top of the stack. This is how UFN expresses nesting without JSON's {}/[] brittleness: an unclosed scope at end-of-line is simply closed implicitly, so a truncated object is still usable.

2.4.Arrays vs Objects

A class is array-typed or object-typed by the dictionary, not by punctuation. An array scope holds repeated item scopes. There is no separate array syntax to get wrong.

2.5.Prose Tail

Everything after the first top-level ::: (triple colon with surrounding spaces — the one readability exception) is verbatim prose to end-of-line: no escaping, no structure. This is the streaming seam — a producer emits the header, then streams prose token by token. The prose tail is top-level only; nested free text is carried as a field.

3.Grammar (ABNF)

line     = element *( ";" element ) [ " ::: " prose ]
element  = field / open / close
field    = key ":" value
open     = acr                  ; bare token, no ":", not starting "/"
close    = "/" [ acr ]          ; bare "/" closes top-of-stack;
                                ; named "/acr" = robustness/resync mode
key      = token                ; from the shared dictionary
acr      = token                ; class name from the shared dictionary
value    = *( vchar / escape )  ; "\;" "\/" "\\" escaped (Section 4)
prose    = *VCHAR               ; verbatim to end-of-line

4.Literals and Escaping

This section is normative and mandatory. Correct round-tripping depends on exactly these rules and no others.

4.1.Reserved Control Tokens

Only the following are reserved. Everything else is data.

;

Field separator.

:

Key/value separator — the first : in a field only.

/

Scope close, when it is a token's leading character.

\

Escape character.

:::

Prose-tail separator (with surrounding spaces).

4.2.Escape Sequences

A backslash escapes a control character that must appear literally in data. There are exactly three sequences; an implementation MUST NOT define others:

4.3.What Does Not Require Escaping

Deliberately, almost nothing needs escaping — this keeps producers reliable:

• Spaces are free everywhere (they are significant inside values and prose).
• A : after the first in a field is data — values may contain colons (timestamps, URLs).
• A / that is not leading is data — paths and dates need no escaping.
• The prose tail is fully verbatim: no character inside it is ever escaped.

4.4.Scalar Lists

A short list of scalar values is carried inside one value, comma-separated, e.g. lb:bug,infra. No scope is opened for the common small-list case.

4.5.Display Names

A reference value MAY carry a human-readable name after a literal |: @:player|Grond. If the name is omitted, the consumer resolves it from its catalogue. For improvised or unknown entities the producer MUST include the name.

5.Fail-Soft Processing

UFN keeps JSON's brittleness out. A conforming parser MUST:

Principle: a partial frame is always better than a parse error. A syntactic failure MUST NOT trigger a consumer's hard fallback; only genuine semantic failure should.

6.Dictionaries

UFN is dictionary-driven: senders and receivers share a token dictionary verbatim — no inference, no fuzzy matching. Object/array classes and field keys are per-domain and declared by the producer.

• A fixed receiver shares the dictionary ahead of time.
• A generic receiver self-orients: the producer SHOULD emit the dictionary it used (keys, enum codes, ligatures) so any consumer can expand the output.

Acronyms and markers MAY be letters, symbols, or sequences; only the control tokens of Section 4.1 are reserved.

7.Encoding Economy

UFN saves structure, not content. The levers below are ranked by measured impact on a 50-task list (against compact JSON at 8201 characters).

7.1.Levers, Ranked by Impact

* on the nested portion. Combined, these reach approximately −59% vs compact JSON and about −44% vs naive UFN.

7.2.Measured Results

The shorter the response, the bigger the win — structural overhead amortizes across less content. Quest updates, warnings, and tool acknowledgements (the most frequent outputs) see the largest savings.

7.3.Latency and Robustness

UFN splits naturally into two phases: a header (~38 tokens, arriving in ~1.5 s on a 25 tok/s decoder) and a streamed prose tail. The consumer can set scene/type/roles from the header while prose appears live, instead of waiting tens of seconds for a complete, parseable JSON document.

7.4.Ligatures

Atomic tokens (keys, enum codes) are tier 1. Ligatures are tier 2: one dictionary token that expands to a combination — the way ROFL or :-) carried whole phrases or states, not glyphs.

• Value ligature — one code for a frequent value-combo (e.g. a status+resolution pair).
• Skeleton ligature — one code for a frequent field pattern of a record.
• Prose ligature — short codes for recurring domain phrases in the prose tail.

A producer SHOULD encode only the Pareto-frequent combinations and SHOULD declare the ligatures it used so a generic receiver can expand them. Because both producer and consumer are LLMs, the shorthand vocabulary can be far richer than IRC ever was, and savings compound exactly where structured output repeats.

8.Recommendations

Operational guidance:

• Keep storage in JSON; emit UFN only at the LLM edge (Section 1.3).
• Share the dictionary verbatim, or emit it so a generic receiver self-orients.
• Prefer short ids over UUIDs, enum codes over words, omit defaults, use the anonymous close.
• Encode only Pareto-frequent ligatures; keep the set learnable.
• Carry long text in the prose tail, never as an escaped field.
• Make the parser fail-soft (Section 5); a partial frame beats an error.

9.Examples

9.1.Flat record (v1-style)

t:241;s:done;ty:feature;ti:kovasite skill

9.2.Nested — a task with a repos array

t;id:9c92;n:241;s:done;ti:kovasite skill;rp;r;id:ce37;nm:pr;/r;r;id:94be;nm:kovanex-server;/r;/rp;/t

Parse: t…/t is an object task; rp…/rp an array of repos; each r…/r an item object.

9.3.Header plus prose tail (game frame)

f:a ; @:player|Grond ; ^:shadow_figure|dark figure ; ~:tavern|Rusty Mug ; s:steel clash, muffled gasp ; l:torchlit ; c:clear ; >:atk shadow_figure ::: The air freezes for one long second...

One line. The header is the structure; everything after ::: is verbatim prose the consumer streams as it arrives.

9.4.The same frame in JSON, for comparison

{"frame":"action","roles":[{"type":"agent","entity_id":"player","name":"Grond"},
{"type":"patient","entity_id":"shadow_figure","name":"dark figure"},
{"type":"location","entity_id":"tavern","name":"Rusty Mug"}],
"atmosphere":{"sounds":["steel clash","muffled gasp"],"light":"torchlit","weather":"clear"},
"state_changes":[{"type":"attack","target":"shadow_figure"}],"prose":"The air freezes..."}

~110 structural tokens against UFN's ~38, and a single missing brace renders all of it unparseable.

10.Versioning

v2 is backward-compatible in spirit: a flat v1 line is a valid v2 line with no open scopes. v2 adds nesting, the tight separator, enum/ligature economy, and the domain-agnostic dictionary model. The original "is UFN worth it" question resolved yes — flat v1 roughly matched JSON, but v2 nesting plus ligatures win decisively.

11.Implementations

kovanex-server/internal/ufn

v2 encoder + parser, nesting, ligatures (reference implementation).

kovanex-server/internal/ufnpb

Protobuf → UFN, shared by the ctl CLI and the MCP server.

tormund/internal/game

v1 game-frame producer/parser (ufn.go, ufn_bridge.go, bundle_ufn.go).

prompt-a-porte/internal/ufn

A second independent implementation.

Shipped surfaces: kovanex-ctl --ufn (list economy + nested get) and MCP tool output in UFN v2 (with a compact-JSON fallback).

12.Conformance (for Agents)

UFN's producers and consumers are LLM agents. The standard is published in agent-consumable form: a curated /llms.txt, the full spec as plain text at /llms-full.txt (single-fetch ingestion), and a machine-readable /ufn.dict.json starter dictionary.

12.1.A conforming producer

• Emits one line per frame; uses ; (general edge) or ; (v1 game profile) as the field separator.
• Uses only \; \/ \\ as escapes; puts long text in the prose tail after ::: .
• Draws keys, classes, and enum codes from a shared dictionary, and SHOULD declare the dictionary (and any ligatures) it used.
• SHOULD apply the economy levers: short ids, enum codes, omit defaults, anonymous close.

12.2.A conforming consumer (parser)

• Classifies tokens by shape (field / open / close); splits a field on the first :.
• Maintains a scope stack; closes unclosed scopes implicitly at end-of-line.
• Is fail-soft per Section 5 — skips unknowns, never hard-fails on syntax.
• Treats everything after the first top-level ::: as verbatim prose.

13.References

Normative.

• [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
• [UFN-v2] Podtsebnev, I., "UFN v2 — USE Frame Notation, generalized", kovanex-server docs/UFN_v2.md, 2026.

Informative.

• [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 8259, December 2017.
• [UFN-v1] Podtsebnev, I., "USE Frame Notation (UFN) v1 — spec", tormund docs/UFN_SPEC.md, 2026.
• [LANG-STACK] "Three-layer language architecture", tormund docs/LANGUAGE_STACK.md.

Author's Address
I. Podtsebnev — Kovanex — [email protected] — https://kovanex.dev