World and topology schema#

The authoritative Rust schema is cw-protocol. JSON uses schema_version: 1; reject unsupported versions rather than silently interpreting them. WorldDefinition::from_json parses and validates the definition.

Field	Meaning
`id`	Nonempty world identity
`profiles`	OS definitions: `id`, `name`, `family`, `home`, `case_sensitive`, `shell`
`computers`	Machine `id`, `profile`, `address`, `user`, optional `node`, initial files, installed applications and packages, and an optional `presentation` (`desktop`, `laptop`, `phone`, `server`)
`network`	Nodes, links, DNS records, routes, explicit `implicit_lan` and gateway policy
`services`	Instance `id`, registered `kind`, placement `node`, domains, `port` (80), `tls` (default `true`: a second listener on 443 answers `https://`), initial state
`metadata`	Owner-side JSON; not an actor observation channel. Two keys are load-bearing: `desktop_themes` maps a computer to an OS shell, and `desktop_apps` declares its application catalog. Both change what an actor sees and can launch — see desktop GUI. `device_presentations` maps a computer to `desktop`, `laptop`, `phone` or `server` (a computer's own `presentation` wins): laptops and phones show a battery, desktop computers and servers none. A phone shell is always a phone; a computer nothing is said about is a desktop computer. `search_engine` is the template the browser's address bar sends searches to (`%s` is the urlencoded query, default `https://google.com/search?q=%s`) — see action families.

A computer's node defaults to its machine ID. Explicit nodes have an address and zone (local, internet, host). Links are required by default; network.implicit_lan: true explicitly enables implicit local reachability. A link names from/to, direction, logical latency_us and loss_per_million. DNS records name an IP address or CNAME target, TTL in logical microseconds, and optional resolver node. Service domains resolve to their placement; clients still need reachable routes and listeners.

Validation checks duplicate identities, profile and node references, address syntax and collisions, listener collisions, DNS definitions and link parameters. The runtime also validates registered service kinds. OS profiles describe synthetic path/shell behavior; they do not boot the corresponding operating system.

Definitions should keep all fixtures and initial state explicit. The seed can vary initialization where an implementation uses its deterministic context; it is not permission to draw host randomness. Runtime state, portable snapshots and world blueprints are different artifacts: a blueprint constructs a world, while a snapshot resumes one.

See creating a world and the company blueprint.

worlds/company-2026/world.json is generated, not hand-written: scripts/build-world.mjs splices in worlds/company-2026/sites/*.json and scripts/build-search-index.mjs builds its search index, with scripts/build-content.sh running the pipeline. The reference computers' device_presentations are declared in build-world.mjs. Edit the inputs, not the output. Your own worlds are of course plain JSON.