VOS

One language for the shape, identity, and behavior of structured data.

VOS (Virtual Object Schema) is a strongly typed schema and operation language for systems that need more than disconnected model definitions. A .vos file can describe persistent tables, domain objects, references, enums, tagged unions, service contracts, and the operations that move data through an application.

The result is a source format that stays readable to people while giving parsers, databases, generators, editors, and conformance tools the same precise contract.

namespace studio::identity

table User {
    @@user_id: uuid,
    @user_name: utf8,
    display_name: utf8,
    manager: &User? = null,
}

class LoginRequest {
    user_name: utf8,
    password: utf8,
}

service IdentityService {
    login(request: LoginRequest) -> User
}

VOS is the schema language in the YY data stack. VON is its companion notation for values and documents: VOS defines what data means; VON carries the data itself.

Most projects describe the same domain repeatedly: database DDL, application types, validation rules, API payloads, migration scripts, and generator configuration. Those copies drift because none of them has enough semantic authority to represent the whole model.

VOS gives that model a single, versionable language:

• Readable by design. Field names, types, references, defaults, and constraints stay visible in compact source.
• Built for durable identity. Stored fields have stable catalog identity beyond their current spelling or source order.
• Schema and operations belong together. Typed construction, projections, queries, updates, and DDL share one object model.
• Host-neutral semantics. Rust, TypeScript, databases, editors, and generators consume one contract instead of inventing local dialects.
• Diagnostics are part of the language. Stable codes and source spans make errors useful in terminals, editors, CI, and products.
• No SQL-shaped escape hatch. VOS is a native object and type language, not a cosmetic frontend that lowers into SQL.

VOS covers both the declarations developers recognize immediately and the less visible contracts production systems eventually need.

Fields use [attribute] name: Type = default. The compact @@id and @name forms mark primary and unique fields without hiding their intent.

let active = User
    .filter(user => user.enabled == true)
    .map(user => user.{
        user_id: user.user_id,
        name: user.display_name,
    })
    .collect()

Operations follow the same object and method vocabulary as the schema. References are inferred from use sites; an explicit .load(...) may document or tune intent, but is not required to make a valid relationship meaningful.

YYDB and YYDS consume VOS as their native DDL and operation language. They do not route VOS through SQL, expose a SQL compatibility grammar, or require applications to think in relational query strings.

External integrations may project a local VOS model onto another storage technology, but that adapter boundary does not change the language contract. The invariant is simple: formal VOS, YYDB, and YYDS surfaces remain SQL-free.

The Rust facade is the most complete parser and language implementation today. The TypeScript package currently provides a lightweight source check and is intentionally narrower; its README states the supported surface explicitly.

vos-language/
├── projects/
│   ├── vos.rs/          Rust facade, parser, AST, inspect, and generation
│   └── vos.ts/          TypeScript API, grammar, extension, and site
├── specifications/
│   └── fixtures/        Shared source, AST, catalog, and diagnostic goldens
├── scripts/             Repository automation
└── projects/vos.ts/vos-skills/   Agent Skills npm package (`@game-gpt/vos-skills`)

Public applications should depend on the facade for their host: vos in Rust or @game-gpt/vos in TypeScript. Internal Rust crates keep the implementation maintainable; they are not competing public APIs.

Language implementations are measured against shared fixtures rather than prose alone. Each case can include normalized source, serialized AST, diagnostics, and catalog identity. This makes parser behavior reviewable and gives future hosts a concrete compatibility target.

cd projects/vos.rs
cargo test -p vos-parser --test conformance

See the fixture guide before adding or updating goldens.

Changes to syntax or semantics should arrive with focused parser coverage and conformance evidence. Keep public APIs behind the host facade, preserve stable diagnostic behavior, and avoid introducing a second schema dialect in a generator or adapter.

cd projects/vos.rs
cargo fmt --all -- --check
cargo check --workspace --all-targets
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

pnpm install
pnpm typecheck
pnpm -r test

VOS is available under the Mozilla Public License 2.0.