{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/onlyworlds-com/json-schema/onlyworlds-com-location-schema.json",
  "title": "Location",
  "description": "A location as the API returns it. Single links are an id or null, multi links an array of ids; extension fields appear inline. `?fields=` returns only the named keys, and `?expand=` replaces the named links' ids with ElementStub objects.",
  "x-generated": "2026-11-20",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/onlyworlds-com-openapi.json#/components/schemas/Location",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "const": "location"
    },
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string",
      "maxLength": 255,
      "description": "Name of the element."
    },
    "description": {
      "type": "string",
      "description": "Any kind of details about the element."
    },
    "supertype": {
      "type": "string",
      "maxLength": 128,
      "description": "The top level classification of the element within its type."
    },
    "subtype": {
      "type": "string",
      "maxLength": 128,
      "description": "The sub level classification through which the element is further sorted within its type."
    },
    "image_url": {
      "type": "string",
      "maxLength": 1024,
      "description": "URL to an image representing the element."
    },
    "form": {
      "type": "string",
      "description": "Visual and environmental aspects of the location."
    },
    "function": {
      "type": "string",
      "description": "Main use, role, or purpose of the location within the world."
    },
    "political_climate": {
      "type": "string",
      "description": "Political structure, stability, and dynamics of the location."
    },
    "customs": {
      "type": "string",
      "description": "Cultural practices, habits, or festivals."
    },
    "infrastructure": {
      "type": "string",
      "description": "Roads, ports, and other physical systems that enable the movement of goods and people."
    },
    "architecture": {
      "type": "string",
      "description": "Look, form, and materials used in the built environment and location design."
    },
    "defensibility": {
      "type": "string",
      "description": "Qualities of natural, constructed, and implemented defenses at the location."
    },
    "founding_date": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Date on which the location was founded, established, or designated."
    },
    "elevation": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Height or elevation of the location relative to surrounding terrain, in the world's distance unit (World distance_unit)."
    },
    "parent_location": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Wider location that this location is part of. A Location's id."
    },
    "vehicle": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "The Object this place is the inside of: a ship, a train, an airship, a walking city, a station that moves. Set it when the place moves with the thing; a place inside another place uses parent_location instead. An Object's id."
    },
    "primary_power": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Institution that has the highest degree of political control over the location. An Institution's id."
    },
    "governing_title": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Governing figure assigned by the location's primary power. A Title's id."
    },
    "zone": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Zone of interest that is associated with the location. A Zone's id."
    },
    "rival": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Location with an active, traditional, or historical rivalry with this one. A Location's id."
    },
    "partner": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Location with active, cooperative, or historical ties to this one. A Location's id."
    },
    "populations": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Distinct collective groups or communities residing within the location. Collective ids, as stored (a write keeps each id once)."
    },
    "secondary_powers": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Institutions with significant political control. Institution ids, as stored (a write keeps each id once)."
    },
    "founders": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Individual(s) who founded or named the location. Character ids, as stored (a write keeps each id once)."
    },
    "cults": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Significant religious constructs practiced or recognized at the location. Construct ids, as stored (a write keeps each id once)."
    },
    "delicacies": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Organisms or other species locally consumed or celebrated as specialty foods. Species ids, as stored (a write keeps each id once)."
    },
    "extraction_methods": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Techniques or strategies used to gather natural resources. Construct ids, as stored (a write keeps each id once)."
    },
    "extraction_goods": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Products and materials that are gathered or obtained. Construct ids, as stored (a write keeps each id once)."
    },
    "industry_methods": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Techniques or workflows used to refine or manufacture goods. Construct ids, as stored (a write keeps each id once)."
    },
    "industry_goods": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Products and materials that are refined or manufactured. Construct ids, as stored (a write keeps each id once)."
    },
    "extraction_markets": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Locations that receive extracted goods through trade, interchange, or seizure. Location ids, as stored (a write keeps each id once)."
    },
    "industry_markets": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Locations that receive industrial goods through trade, interchange, or seizure. Location ids, as stored (a write keeps each id once)."
    },
    "currencies": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Trade media recognized or circulated at the location. Construct ids, as stored (a write keeps each id once)."
    },
    "buildings": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Notable structural objects at the location. Object ids, as stored (a write keeps each id once)."
    },
    "building_methods": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Techniques or systems used to construct structures at the location. Construct ids, as stored (a write keeps each id once)."
    },
    "fighters": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Military units or forces responsible for defending the location. Construct ids, as stored (a write keeps each id once)."
    },
    "defensive_objects": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Objects or installations for defending the location. Object ids, as stored (a write keeps each id once)."
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    },
    "change_seq": {
      "type": "integer",
      "description": "The world change sequence at this element's last write."
    },
    "created_by": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "readOnly": true,
      "description": "The world membership that created this element, or null when the world's owner did. Members only: absent for the public, as `doors` is."
    },
    "changed_by": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "readOnly": true,
      "description": "The world membership that last changed this element, or null when the world's owner (or the server) did, or no write has touched it since doors were recorded: null with a non-null `changed_via` other than `server` is the world owner's write (the owner is the account, not a membership); null with `server` is the server's own write; null in both is a row from before writers were recorded. An id whose row on GET /members has `status: removed` is a former member's write: the id outlives the membership (removed, left, or its account deleted), and is never the owner's. Members only: absent for the public, as `doors` is."
    },
    "changed_via": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "seat",
        "mcp",
        "declared",
        "api",
        "v1",
        "sync",
        "server",
        "site",
        null
      ],
      "readOnly": true,
      "description": "The door of the last change: `seat` (an AI seat), `mcp` (the MCP server), `declared` (the request sent an X-OW-Agent header), `api`, `v1`, `sync` (the mobile app's sync), `site` (the owner on onlyworlds.com) or `server` (the server, on its own behalf). The first three are the doors the platform marks as an AI's. Null: no write since doors were recorded. Members only: absent for the public, as `doors` is."
    },
    "changed_client": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 32,
      "readOnly": true,
      "description": "The name the client gave itself on the last change, in its X-OW-Client header (`atlas`, `lantern`, `sdk`): the client's claim, never proof, and it changes nothing about the door the change came through (that is `changed_via`). Null: no name sent, a value outside the rule, a server write, or a change from before names were recorded. Members only: absent for the public, as `doors` is."
    },
    "doors": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": {
        "type": "string",
        "format": "date-time"
      },
      "maxProperties": 16,
      "readOnly": true,
      "description": "Where this element has been: one key per tool that wrote it, each with the time of that tool's last write (the same string as `updated_at` after that write, so the newest key's time is this body's `updated_at`). The key is the name the client gave in its X-OW-Client header (`atlas`, `lantern`) when it sent one, else the door the write came through (`api`, `seat`, `mcp`, `server` and the other `changed_via` words), never both for one write. At most 16 keys: a new one past that drops the key with the oldest time. Members only: served to the world's owner and every member (co-builders, contributors, guests and AI seats); absent for the public, absent on a known-of stub, and never in the change feed or a world file. Null: no write since the history was recorded. A write carrying it is accepted and the key ignored."
    },
    "known_of": {
      "type": "boolean",
      "const": true,
      "readOnly": true,
      "description": "Present, and true, only on an element this reader knows of but does not see whole: a guest or player reaches it only because its own Character's sheet links to it (one step out). Such a row keeps `id`, `type`, `name`, `description`, `supertype`, `subtype`, `image_url`, `created_at`, `updated_at` and `change_seq`, and its type's public fields (none for a location); every other field reads as unset (text \"\", numbers and single links null, multi links [], `created_by`, `changed_by` and `changed_via` null, no `doors`, no extension fields), its files are 404, and search matches only what it keeps. Absent: the element is whole. Any other grant (it names the reader's Character, the reader knows it, it is on the roster, the reader made it) makes it whole; a hidden element is never even a stub, whatever its public fields. Read-only: a write carrying `known_of` is refused (`known_of_not_writable`)."
    },
    "hidden": {
      "type": "boolean",
      "const": true,
      "readOnly": true,
      "description": "Present, and true, only when the world's owner or a co-builder hid this element and this reader still sees it: the owner, a co-builder, a key the owner minted, or the member who made it (to every other reader it does not exist). Absent otherwise, never false. A world file (the site's download) never carries it. Sent back in an update, it is ignored: hide and unhide an existing element through PUT and DELETE /{type}/{id}/hidden. Sent on a create, `hidden: true` creates the element hidden (the write body's `hidden`)."
    }
  },
  "patternProperties": {
    "^(atlas_|shadow_|x_)": {
      "description": "Extension field, stored opaquely and returned verbatim (any JSON value; at most 65536 bytes of extensions per element, counted as compact UTF-8 JSON). For the public reader, a review mark (`x_review_checked`) that is an object holding `by` is served with `by` null and its other keys as stored."
    }
  },
  "additionalProperties": false,
  "required": [
    "type",
    "id",
    "name",
    "description",
    "supertype",
    "subtype",
    "image_url",
    "form",
    "function",
    "political_climate",
    "customs",
    "infrastructure",
    "architecture",
    "defensibility",
    "founding_date",
    "elevation",
    "parent_location",
    "vehicle",
    "primary_power",
    "governing_title",
    "zone",
    "rival",
    "partner",
    "populations",
    "secondary_powers",
    "founders",
    "cults",
    "delicacies",
    "extraction_methods",
    "extraction_goods",
    "industry_methods",
    "industry_goods",
    "extraction_markets",
    "industry_markets",
    "currencies",
    "buildings",
    "building_methods",
    "fighters",
    "defensive_objects",
    "created_at",
    "updated_at",
    "change_seq"
  ]
}