Worlds
A world is the top-level container for elements, representing a complete setting at any scope you define. Every element belongs to exactly one world, and a world key reads or writes exactly one world.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string (uuid) | No (server-assigned) | Unique world identifier (UUIDv7) |
name |
string | Yes | Display name; it cannot be empty |
description |
string | No | Text description |
image_url |
string (url) | No | Cover image or representative visual |
Timeline
Section titled “Timeline”| Field | Type | Required | Description |
|---|---|---|---|
time_format_names |
array of strings | No | Names of each time step: ["Day", "Week", "Month", "Year"], or custom names like ["Sol", "Cycle", "Season", "Era"] |
time_format_equivalents |
array of integers | No | Basic units per step, e.g. [1, 7, 30, 365] (older worlds on onlyworlds.com may hold them as strings) |
time_basic_unit |
string | No | Smallest time unit (e.g. "Day" or "Hour") |
time_range_min |
integer | No | Earliest tracked time point |
time_range_max |
integer | No | Latest tracked time point |
time_range_current |
integer | No | Current time in your world. The standard’s YAML names this field time_current. |
Element fields that hold a moment, such as a Character’s birth_date or an Event’s start_date, are integers in the world’s time units.
Timeline Examples
Section titled “Timeline Examples”Fantasy world with a custom calendar:
time_format_names:["Sun", "Tenday", "Moon", "Turning"]time_basic_unit:"Sun"time_range_current:1247(year 1247 of the Third Age)
Science fiction setting with stardates:
time_format_names:["Cycle", "Rotation", "Orbit", "Epoch"]time_basic_unit:"Cycle"time_range_min:0time_range_max:128256
Timeline fields work with Events and Narratives.
Some element fields hold a measure: a Character’s height and weight, a Creature’s speed, a Location’s elevation, an Ability’s range. The numbers are whole, and the world says what they count in, with three optional free-text settings:
| Field | Type | Counts | Used by |
|---|---|---|---|
length_unit |
string | Lengths | Character and Creature height |
mass_unit |
string | Masses | Character, Creature, Object and Species weight |
distance_unit |
string | Distances | Ability range, Creature speed, Location elevation |
The value is free text, written as the world means it. Recommended where one fits: mm, cm, m, in, ft for lengths; g, kg, t, lb for masses; m, km, ft, mi for distances. A world’s own unit (hands, stone, leagues) is shown as written, and nothing is converted: a tool can convert what it recognises and shows the rest verbatim. Empty means not set. A number stays a bare number in the element; only the world names its unit.
Platform Fields
Section titled “Platform Fields”onlyworlds.com adds fields of its own to the world it serves. They are part of the platform, not the standard.
| Field | Type | Description |
|---|---|---|
public_read |
boolean | Whether the world is open to read |
owner_character |
string (uuid) or null | The owner’s own Character in this world (“this Character is me”), or null |
created_at |
string (date-time) | When the world was created |
updated_at |
string (date-time) | When the world last changed |
The world named by a key is GET /api/v2/world/. Only the world’s owner can change it, with PATCH; the writable fields are name, description, image_url, the timeline fields, the three unit settings and owner_character.
Legacy and Account Fields
Section titled “Legacy and Account Fields”The standard also defines these. The v2 API does not return them.
| Field | Type | Description |
|---|---|---|
api_key |
string | Legacy 10-character key, not issued for new worlds. Use world keys (ow_w_ / ow_r_) minted in the account portal. |
version |
string | The OnlyWorlds format version the world conforms to |
user |
string (uuid) | Owner’s account identifier (not exposed on the API) |