{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/onlyworlds-com/json-schema/onlyworlds-com-location-write-schema.json",
  "title": "LocationWrite",
  "description": "A full location write (POST creates; PUT creates or fully replaces, resetting omitted fields to empty). Any key that is neither a field below nor an extension field (atlas_*, shadow_*, x_*) is a 422, including the server-managed type, created_at, updated_at and change_seq.",
  "x-generated": "2026-11-20",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/onlyworlds-com-openapi.json#/components/schemas/LocationWrite",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "POST: optional client-minted id (any RFC 4122 UUID; the server mints a UUIDv7 otherwise). PUT/PATCH: ignored, the path id wins."
    },
    "name": {
      "type": [
        "string",
        "null"
      ],
      "description": "Name of the element. null stores ''.",
      "maxLength": 255
    },
    "description": {
      "type": [
        "string",
        "null"
      ],
      "description": "Any kind of details about the element. null stores ''."
    },
    "supertype": {
      "type": [
        "string",
        "null"
      ],
      "description": "The top level classification of the element within its type. null stores ''.",
      "maxLength": 128
    },
    "subtype": {
      "type": [
        "string",
        "null"
      ],
      "description": "The sub level classification through which the element is further sorted within its type. null stores ''.",
      "maxLength": 128
    },
    "image_url": {
      "type": [
        "string",
        "null"
      ],
      "description": "URL to an image representing the element. null stores ''.",
      "maxLength": 1024
    },
    "form": {
      "type": [
        "string",
        "null"
      ],
      "description": "Visual and environmental aspects of the location. null stores ''."
    },
    "function": {
      "type": [
        "string",
        "null"
      ],
      "description": "Main use, role, or purpose of the location within the world. null stores ''."
    },
    "political_climate": {
      "type": [
        "string",
        "null"
      ],
      "description": "Political structure, stability, and dynamics of the location. null stores ''."
    },
    "customs": {
      "type": [
        "string",
        "null"
      ],
      "description": "Cultural practices, habits, or festivals. null stores ''."
    },
    "infrastructure": {
      "type": [
        "string",
        "null"
      ],
      "description": "Roads, ports, and other physical systems that enable the movement of goods and people. null stores ''."
    },
    "architecture": {
      "type": [
        "string",
        "null"
      ],
      "description": "Look, form, and materials used in the built environment and location design. null stores ''."
    },
    "defensibility": {
      "type": [
        "string",
        "null"
      ],
      "description": "Qualities of natural, constructed, and implemented defenses at the location. null stores ''."
    },
    "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. Links a Location: an existing one in this world."
    },
    "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. Links an Object: an existing one in this world."
    },
    "primary_power": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Institution that has the highest degree of political control over the location. Links an Institution: an existing one in this world."
    },
    "governing_title": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Governing figure assigned by the location's primary power. Links a Title: an existing one in this world."
    },
    "zone": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Zone of interest that is associated with the location. Links a Zone: an existing one in this world."
    },
    "rival": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Location with an active, traditional, or historical rivalry with this one. Links a Location: an existing one in this world."
    },
    "partner": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Location with active, cooperative, or historical ties to this one. Links a Location: an existing one in this world."
    },
    "populations": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Distinct collective groups or communities residing within the location. Links Collective elements; replaces the whole list (null is the same as []; a null entry in it is refused; an id named twice is kept once, in its first place). Every id must name an existing one in this world."
    },
    "secondary_powers": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Institutions with significant political control. Links Institution elements; replaces the whole list (null is the same as []; a null entry in it is refused; an id named twice is kept once, in its first place). Every id must name an existing one in this world."
    },
    "founders": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Individual(s) who founded or named the location. Links Character elements; replaces the whole list (null is the same as []; a null entry in it is refused; an id named twice is kept once, in its first place). Every id must name an existing one in this world."
    },
    "cults": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Significant religious constructs practiced or recognized at the location. Links Construct elements; replaces the whole list (null is the same as []; a null entry in it is refused; an id named twice is kept once, in its first place). Every id must name an existing one in this world."
    },
    "delicacies": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Organisms or other species locally consumed or celebrated as specialty foods. Links Species elements; replaces the whole list (null is the same as []; a null entry in it is refused; an id named twice is kept once, in its first place). Every id must name an existing one in this world."
    },
    "extraction_methods": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Techniques or strategies used to gather natural resources. Links Construct elements; replaces the whole list (null is the same as []; a null entry in it is refused; an id named twice is kept once, in its first place). Every id must name an existing one in this world."
    },
    "extraction_goods": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Products and materials that are gathered or obtained. Links Construct elements; replaces the whole list (null is the same as []; a null entry in it is refused; an id named twice is kept once, in its first place). Every id must name an existing one in this world."
    },
    "industry_methods": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Techniques or workflows used to refine or manufacture goods. Links Construct elements; replaces the whole list (null is the same as []; a null entry in it is refused; an id named twice is kept once, in its first place). Every id must name an existing one in this world."
    },
    "industry_goods": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Products and materials that are refined or manufactured. Links Construct elements; replaces the whole list (null is the same as []; a null entry in it is refused; an id named twice is kept once, in its first place). Every id must name an existing one in this world."
    },
    "extraction_markets": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Locations that receive extracted goods through trade, interchange, or seizure. Links Location elements; replaces the whole list (null is the same as []; a null entry in it is refused; an id named twice is kept once, in its first place). Every id must name an existing one in this world."
    },
    "industry_markets": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Locations that receive industrial goods through trade, interchange, or seizure. Links Location elements; replaces the whole list (null is the same as []; a null entry in it is refused; an id named twice is kept once, in its first place). Every id must name an existing one in this world."
    },
    "currencies": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Trade media recognized or circulated at the location. Links Construct elements; replaces the whole list (null is the same as []; a null entry in it is refused; an id named twice is kept once, in its first place). Every id must name an existing one in this world."
    },
    "buildings": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Notable structural objects at the location. Links Object elements; replaces the whole list (null is the same as []; a null entry in it is refused; an id named twice is kept once, in its first place). Every id must name an existing one in this world."
    },
    "building_methods": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Techniques or systems used to construct structures at the location. Links Construct elements; replaces the whole list (null is the same as []; a null entry in it is refused; an id named twice is kept once, in its first place). Every id must name an existing one in this world."
    },
    "fighters": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Military units or forces responsible for defending the location. Links Construct elements; replaces the whole list (null is the same as []; a null entry in it is refused; an id named twice is kept once, in its first place). Every id must name an existing one in this world."
    },
    "defensive_objects": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Objects or installations for defending the location. Links Object elements; replaces the whole list (null is the same as []; a null entry in it is refused; an id named twice is kept once, in its first place). Every id must name an existing one in this world."
    },
    "world": {
      "description": "Tolerated and ignored: the API-Key decides the world."
    },
    "created_by": {
      "description": "Tolerated and ignored: the server records who created an element."
    },
    "changed_by": {
      "description": "Tolerated and ignored: the server records who last changed an element, and through which door."
    },
    "changed_via": {
      "description": "Tolerated and ignored: the server records who last changed an element, and through which door."
    },
    "changed_client": {
      "description": "Tolerated and ignored: a client names itself in the X-OW-Client header, never in the body."
    },
    "doors": {
      "description": "Tolerated and ignored: the server records where an element has been."
    },
    "hidden": {
      "type": [
        "boolean",
        "null"
      ],
      "default": false,
      "description": "On a create (POST, a PUT whose id is new, or a /bulk item that creates): true creates the element hidden from its first moment. Only the world's owner key or a co-builder's (a person's or a seat's) may send it; any other key is refused (403 hidden_not_allowed) and nothing is created. The element is never served to a reader who cannot see hidden elements, and /changes never carries its body to them: a contributor gets one delete row with reason `hidden` at the element's change_seq, a guest nothing; the owner and co-builders get it with `hidden: true`. false, null or absent: a visible element, as ever. Any other value is a 422 on a create. Where the server has the hidden mark switched off, true is a 422 (param hidden) and nothing is created. On a PUT that replaces an existing element it is ignored: hide and unhide through PUT and DELETE /{type}/{id}/hidden."
    },
    "x_served_trimmed": {
      "not": {},
      "description": "Refused (422 served_trimmed_not_writable): served only, see the Narrative read schema (a message) and the Construct read schema (a lens)."
    }
  },
  "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)."
    }
  },
  "additionalProperties": false,
  "required": [
    "name"
  ]
}