{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/immix/json-schema/immix-upsert-user-body-schema.json",
  "title": "UpsertUserBody",
  "description": "UpsertUser with edge-stamped fields (userId) removed — the edge sets them and refuses a body value, and edge aliases (preset for capabilities) added — either spelling names the field and at least one is required (the anyOf); both stated must agree, and the alias is resolved at the edge, never on the wire.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/immix-users-api-openapi.yml#/components/schemas/UpsertUserBody",
  "type": "object",
  "properties": {
    "targetUserId": {
      "type": [
        "integer",
        "null"
      ],
      "description": "0 = create."
    },
    "expectedVersion": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^-?[0-9]+$",
      "description": "int64 as a decimal JSON string"
    },
    "kind": {
      "$ref": "#/$defs/UpsertUserBodyKind",
      "description": "UNKNOWN is the unset sentinel: outputs only — as input, omit the field instead; explicit UNKNOWN refuses 400. The value set is append-only: a consumer READING this field treats an unknown name as UNKNOWN, never as an error; as input an unknown name refuses 400 — the parse is strict"
    },
    "capabilities": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/UpsertUserBodyCapabilitiesItem"
      },
      "description": "a set (SBE bit-set) served as the array of its scope strings — each choice spelled <route family>:<verb> (the schema's camel-cased choice name de-camelled: accountAddressesApprove is account-addresses:approve) — in declared order; empty = none set, never null. The choice set is append-only: a consumer READING this field skips an unknown name, never errors; as input an unknown or repeated name refuses 400 — the parse is strict"
    },
    "name": {
      "type": "string"
    },
    "idpUserRef": {
      "type": "string",
      "description": "Empty = unstated, which keeps the current binding (a rename or an admission never strands a login); a value binds or re-binds. Refused IDP_REF_TAKEN when another row of the organisation carries it."
    },
    "preset": {
      "$ref": "#/$defs/UpsertUserBodyPreset",
      "description": "A named capability bundle the edge expands to its scope strings and never forwards — the row records bits, never a preset name: INITIATOR (the six maker-checker families' propose bits), APPROVER (initiator plus their approve bits), ADMIN (approver plus users:manage and portfolios:manage), TRADER (orders:trade), TREASURY (the account, address and asset/chain policy families, both verbs), PLATFORM (orgs:propose and orgs:approve, inside the internal platform org only). Either preset or capabilities names the set; both stated must agree, else 400. x-immix-preset-capabilities is the expansion."
    }
  },
  "required": [
    "kind",
    "name"
  ],
  "$defs": {
    "UpsertUserBodyCapabilitiesItem": {
      "type": "string",
      "enum": [
        "users:manage",
        "credentials:propose",
        "credentials:approve",
        "accounts:propose",
        "accounts:approve",
        "account-addresses:propose",
        "account-addresses:approve",
        "portfolios:manage",
        "asset-policies:propose",
        "asset-policies:approve",
        "chain-policies:propose",
        "chain-policies:approve",
        "trading-policies:propose",
        "trading-policies:approve",
        "orders:trade",
        "orgs:propose",
        "orgs:approve",
        "algos:manage"
      ],
      "title": "UpsertUserBodyCapabilitiesItem"
    },
    "UpsertUserBodyKind": {
      "type": "string",
      "enum": [
        "UNKNOWN",
        "HUMAN",
        "SERVICE"
      ],
      "description": "UNKNOWN is the unset sentinel: outputs only — as input, omit the field instead; explicit UNKNOWN refuses 400. The value set is append-only: a consumer READING this field treats an unknown name as UNKNOWN, never as an error; as input an unknown name refuses 400 — the parse is strict",
      "title": "UpsertUserBodyKind"
    },
    "UpsertUserBodyPreset": {
      "type": "string",
      "enum": [
        "INITIATOR",
        "APPROVER",
        "ADMIN",
        "TRADER",
        "TREASURY",
        "PLATFORM"
      ],
      "description": "A named capability bundle the edge expands to its scope strings and never forwards — the row records bits, never a preset name: INITIATOR (the six maker-checker families' propose bits), APPROVER (initiator plus their approve bits), ADMIN (approver plus users:manage and portfolios:manage), TRADER (orders:trade), TREASURY (the account, address and asset/chain policy families, both verbs), PLATFORM (orgs:propose and orgs:approve, inside the internal platform org only). Either preset or capabilities names the set; both stated must agree, else 400. x-immix-preset-capabilities is the expansion.",
      "title": "UpsertUserBodyPreset"
    }
  }
}