{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/immix/json-schema/immix-user-row-schema.json",
  "title": "UserRow",
  "description": "A user as the API serves it: the `UserUpdated` record plus the row extras (`globalSequence`; the deprecated `unscaled`, never present since 0.3.3) — the one shape its reads and its commands answer.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/immix-users-api-openapi.yml#/components/schemas/UserRow",
  "type": "object",
  "properties": {
    "userId": {
      "type": "integer",
      "description": "Sticky entity key."
    },
    "version": {
      "type": "string",
      "pattern": "^-?[0-9]+$",
      "description": "Monotonic per entity. int64 as a decimal JSON string"
    },
    "orgId": {
      "type": "integer",
      "description": "Membership — stamped by the owner from the actor's org, or from the discovery's parent ref."
    },
    "status": {
      "$ref": "#/$defs/UserUpdatedStatus",
      "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"
    },
    "kind": {
      "$ref": "#/$defs/UserUpdatedKind",
      "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/UserUpdatedCapabilitiesItem"
      },
      "description": "The user's capabilities — what they may do; empty on a discovered row, and on an invited first administrator until the organisation is activated. 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"
    },
    "invitedByUserId": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Who proposed or invited this user: the maker on an organisation's first administrator — stamped at the proposal, whether or not an email follows — and the inviter on an invited member; absent — null in the API, 0 on the wire — on a row created directly or discovered."
    },
    "inviteExpiresAtNs": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^-?[0-9]+$",
      "description": "The deadline the row was last invited under: the inviting command's position time plus its stated lifetime; absent — null in the API, 0 on the wire — on a row never invited. Kept after the claim and after a cancel — status and invitationState say whether an invitation is open. A first login after it is refused INVITATION_EXPIRED and a re-invite opens a fresh deadline. int64 as a decimal JSON string"
    },
    "invitationState": {
      "$ref": "#/$defs/UserUpdatedInvitationState",
      "description": "Where the invitation stands: PENDING until the platform has created it with the identity provider, then SENT, ALREADY_MEMBER or FAILED; ACCEPTED once the invitee has signed in; NONE where none was created (a first administrator before activation). Kept after a cancel — an invitation is open while status is INVITED. NONE is the unset sentinel: outputs only — as input, omit the field instead; explicit NONE refuses 400. The value set is append-only: a consumer READING this field treats an unknown name as NONE, never as an error; as input an unknown name refuses 400 — the parse is strict"
    },
    "name": {
      "type": "string",
      "description": "Platform name — per-org unique among live users with a non-empty name; empty until admission."
    },
    "idpUserRef": {
      "type": "string",
      "description": "The identity provider's subject, opaque, never parsed: a token's sub resolves to this row inside the token's organisation. Empty = unbound (a locally authenticated user). Unique among all the organisation's users, disabled included — a subject binds for the life of its row, and a second binding is refused IDP_REF_TAKEN."
    },
    "displayName": {
      "type": "string",
      "description": "What the IdP stated at discovery (the name, else email, else nickname claim); informational, never a key."
    },
    "email": {
      "type": "string",
      "description": "The address the user was invited at, lowercased — the address a first login must have verified to claim the row, kept afterwards as the address the user was registered by. Empty on a row no invitation created. Unique among the organisation's invited and active users (EMAIL_TAKEN)."
    },
    "idpInvitationRef": {
      "type": "string",
      "description": "The identity provider's id for the invitation the platform created, as the platform reported it; informational, never a key; empty until reported."
    },
    "globalSequence": {
      "$ref": "#/$defs/GlobalSequenceValue"
    },
    "unscaled": {
      "type": "boolean",
      "description": "Never present since 0.3.3: every money value on this API states its own scale on the wire — a policy amount or cap since 0.3.3, an order's and an execution's since 0.3.2, a balance's since 0.3.1 — so a row is never served raw, whether or not this member holds the asset or instrument it references. Kept, deprecated, so a client generated from 0.3.2 still compiles; it goes at the next major.",
      "deprecated": true
    }
  },
  "required": [
    "userId",
    "version",
    "orgId",
    "status",
    "kind",
    "capabilities",
    "name",
    "displayName",
    "globalSequence"
  ],
  "$defs": {
    "GlobalSequenceValue": {
      "type": "string",
      "pattern": "^[0-9]+$",
      "description": "The position as a decimal string — the last change this member had applied, orders, balance readings and algo instances included.",
      "title": "GlobalSequenceValue"
    },
    "UserUpdatedCapabilitiesItem": {
      "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": "UserUpdatedCapabilitiesItem"
    },
    "UserUpdatedInvitationState": {
      "type": "string",
      "enum": [
        "NONE",
        "PENDING",
        "SENT",
        "ALREADY_MEMBER",
        "FAILED",
        "ACCEPTED"
      ],
      "description": "Where the invitation stands: PENDING until the platform has created it with the identity provider, then SENT, ALREADY_MEMBER or FAILED; ACCEPTED once the invitee has signed in; NONE where none was created (a first administrator before activation). Kept after a cancel — an invitation is open while status is INVITED. NONE is the unset sentinel: outputs only — as input, omit the field instead; explicit NONE refuses 400. The value set is append-only: a consumer READING this field treats an unknown name as NONE, never as an error; as input an unknown name refuses 400 — the parse is strict",
      "title": "UserUpdatedInvitationState"
    },
    "UserUpdatedKind": {
      "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": "UserUpdatedKind"
    },
    "UserUpdatedStatus": {
      "type": "string",
      "enum": [
        "UNKNOWN",
        "DISCOVERED",
        "ACTIVE",
        "DISABLED",
        "INVITED"
      ],
      "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": "UserUpdatedStatus"
    }
  }
}