{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/onlyworlds-com/json-schema/onlyworlds-com-construct-schema.json",
  "title": "Construct",
  "description": "A construct 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/Construct",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "const": "construct"
    },
    "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."
    },
    "rationale": {
      "type": "string",
      "description": "The internal reasoning, structure, or justification of how the construct functions or makes sense within the world."
    },
    "history": {
      "type": "string",
      "description": "The historical development or ideation of the construct, and its place in wider historical contexts."
    },
    "status": {
      "type": "string",
      "description": "The present condition or operational status of the construct."
    },
    "reach": {
      "type": "string",
      "description": "The geographic, cultural, or political extent of the construct's influence."
    },
    "start_date": {
      "type": [
        "integer",
        "null"
      ],
      "description": "The point in time when the construct began or was first established, in the world's time unit (World time_basic_unit)."
    },
    "end_date": {
      "type": [
        "integer",
        "null"
      ],
      "description": "The point in time when the construct ceased to function or lost its meaning."
    },
    "founder": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Character who conceived or initiated the construct. A Character's id."
    },
    "custodian": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Institution maintaining, enforcing, or exploiting the construct. An Institution's id."
    },
    "characters": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Characters relevant to the construct. Character ids, as stored (a write keeps each id once)."
    },
    "objects": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Objects relevant to the construct. Object ids, as stored (a write keeps each id once)."
    },
    "locations": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Locations relevant to the construct. Location ids, as stored (a write keeps each id once)."
    },
    "species": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Species relevant to the construct. Species ids, as stored (a write keeps each id once)."
    },
    "creatures": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Creatures relevant to the construct. Creature ids, as stored (a write keeps each id once)."
    },
    "institutions": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Institutions relevant to the construct. Institution ids, as stored (a write keeps each id once)."
    },
    "traits": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Traits relevant to the construct. Trait ids, as stored (a write keeps each id once)."
    },
    "collectives": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Collectives relevant to the construct. Collective ids, as stored (a write keeps each id once)."
    },
    "zones": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Zones relevant to the construct. Zone ids, as stored (a write keeps each id once)."
    },
    "abilities": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Abilities relevant to the construct. Ability ids, as stored (a write keeps each id once)."
    },
    "phenomena": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Phenomena relevant to the construct. Phenomenon ids, as stored (a write keeps each id once)."
    },
    "languages": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Languages relevant to the construct. Language ids, as stored (a write keeps each id once)."
    },
    "families": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Families relevant to the construct. Family ids, as stored (a write keeps each id once)."
    },
    "relations": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Relations relevant to the construct. Relation ids, as stored (a write keeps each id once)."
    },
    "titles": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Titles relevant to the construct. Title ids, as stored (a write keeps each id once)."
    },
    "constructs": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Other constructs relevant to the construct. Construct ids, as stored (a write keeps each id once)."
    },
    "events": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Events relevant to the construct. Event ids, as stored (a write keeps each id once)."
    },
    "narratives": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Narratives relevant to the construct. Narrative 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 construct); 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`)."
    },
    "x_served_trimmed": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "characters",
          "objects",
          "locations",
          "species",
          "creatures",
          "institutions",
          "traits",
          "collectives",
          "zones",
          "abilities",
          "phenomena",
          "languages",
          "families",
          "relations",
          "constructs",
          "events",
          "narratives",
          "notes"
        ]
      },
      "minItems": 1,
      "uniqueItems": true,
      "readOnly": true,
      "description": "Served only, on a lens (a Construct with supertype Lens, the lens profile, profiles/lens.md): present when one or more anchor ids were left out because this reader may not see them, and it names those anchor fields in the schema's order, then `notes` when the note on such an anchor was left out of x_lens with it (a note keyed to any other element you cannot see is left out too, unmarked); never which ids, never how many. A lens that names an anchor is never a filter: read a lens whose anchor fields are empty and that carries this key as anchored (it resolves to nothing for you), never as a filter over the whole world. Absent when nothing was left out, and for the keyless public reader. The world's owner, its co-builders and keys the owner minted read every id, so their own reading never carries it; they meet it when they read as someone else: with `?as=`, and in a Character's context read with `mode=voice`, whose bodies are served as she reads them. An answer that carries it is sent `Cache-Control: private, no-store`. Never written: a body carrying it is a 422 (`served_trimmed_not_writable`) on every write, /bulk item by item."
    }
  },
  "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",
    "rationale",
    "history",
    "status",
    "reach",
    "start_date",
    "end_date",
    "founder",
    "custodian",
    "characters",
    "objects",
    "locations",
    "species",
    "creatures",
    "institutions",
    "traits",
    "collectives",
    "zones",
    "abilities",
    "phenomena",
    "languages",
    "families",
    "relations",
    "titles",
    "constructs",
    "events",
    "narratives",
    "created_at",
    "updated_at",
    "change_seq"
  ]
}