PersonaWrite

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/usewrit-app/json-schema/usewrit-app-persona-write-schema.json",
  "title": "PersonaWrite",
  "description": "Shared create/update payload. Plaintext secrets (`password`, `extra_login_fields`, `totp_seed`, `proxy_*`) are sealed by the handler and never echoed. Several fields distinguish \"absent = untouched\" from \"explicit null = clear\" (`description`, `target_domain`, `login_username`, `fingerprint`). Secrets follow cloud replace semantics: sending `password`/`extra_login_fields` replaces the whole credential set (empty ⇒ cleared); an empty-string `totp_seed`/`proxy_server` clears that blob. Unknown (cloud-only) fields are ignored.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/writ-agent.yaml#/components/schemas/PersonaWrite",
  "type": "object",
  "properties": {
    "name": {
      "type": [
        "string",
        "null"
      ],
      "description": "Required (non-empty) on create; renames on update (must stay unique)."
    },
    "description": {
      "type": [
        "string",
        "null"
      ],
      "description": "Explicit null clears."
    },
    "target_domain": {
      "type": [
        "string",
        "null"
      ],
      "description": "Explicit null clears."
    },
    "login_username": {
      "type": [
        "string",
        "null"
      ],
      "description": "Literal username or `{{vault:key.username}}` ref; explicit null clears."
    },
    "password": {
      "type": [
        "string",
        "null"
      ],
      "description": "Plaintext password or `{{vault:key.password}}` ref; empty clears the credential set."
    },
    "extra_login_fields": {
      "type": [
        "object",
        "null"
      ],
      "description": "Additional plaintext login fields `{name: value}`.",
      "additionalProperties": {
        "type": "string"
      }
    },
    "twofa_method": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "none",
        "totp",
        "email_otp",
        "sms",
        null
      ]
    },
    "totp_seed": {
      "type": [
        "string",
        "null"
      ],
      "description": "Plaintext base32 seed; empty string on update clears the stored seed."
    },
    "totp_digits": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int64"
    },
    "totp_period_seconds": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int64"
    },
    "totp_algorithm": {
      "type": [
        "string",
        "null"
      ]
    },
    "email_otp_mode": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "oauth_mailbox",
        "relay",
        null
      ]
    },
    "relay_address": {
      "type": [
        "string",
        "null"
      ]
    },
    "otp_extract_config": {
      "type": [
        "object",
        "null"
      ],
      "description": "Email-OTP extraction hints (object); null clears."
    },
    "fingerprint": {
      "type": [
        "object",
        "null"
      ],
      "description": "`{user_agent, locale, timezone}` object to pin; explicit null unpins."
    },
    "proxy_server": {
      "type": [
        "string",
        "null"
      ],
      "description": "BYO proxy server; non-empty requires `proxy_lawful_use_ack`; empty clears."
    },
    "proxy_username": {
      "type": [
        "string",
        "null"
      ]
    },
    "proxy_password": {
      "type": [
        "string",
        "null"
      ]
    },
    "proxy_lawful_use_ack": {
      "type": [
        "boolean",
        "null"
      ]
    },
    "is_active": {
      "type": [
        "boolean",
        "null"
      ]
    }
  }
}