PublicPersonResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/ishlabs-io/json-schema/ishlabs-io-public-person-response-schema.json",
  "title": "PublicPersonResponse",
  "description": "One person, as an external integrator sees them.\n\nThe field list is CLOSED and hand-maintained. It carries who the person is\n(identity + demographics + interests) and nothing about how ish came to\nhold that row: no moderation verdict, no publisher, no viewer-specific\nstate, no internal config pointer, no custom fields.",
  "x-generated": "2026-11-13",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/ishlabs-io-openapi.json#/components/schemas/PublicPersonResponse",
  "properties": {
    "accessibility_profile": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "description": "Declared accessibility needs, as a nested object of boolean and enum flags. Only non-default keys are present. An open union: new keys appear over time.",
      "title": "Accessibility Profile"
    },
    "archived_at": {
      "anyOf": [
        {
          "format": "date-time",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "When this person was archived, or null while they are live. An archived person is hidden from the default listing and closed to edits, but stays readable by id and keeps every session that ran for them intact. `POST .../restore` clears it.",
      "title": "Archived At"
    },
    "avatar_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Publicly fetchable avatar image, when one exists.",
      "title": "Avatar Url"
    },
    "bio": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Free-text background in the person's own register. This is the bulk of what the model is told about them when a session runs.",
      "title": "Bio"
    },
    "city": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "City"
    },
    "country": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Country"
    },
    "created_at": {
      "format": "date-time",
      "title": "Created At",
      "type": "string"
    },
    "date_of_birth": {
      "anyOf": [
        {
          "format": "date",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Date Of Birth"
    },
    "education_level": {
      "anyOf": [
        {
          "$ref": "#/$defs/EducationLevel"
        },
        {
          "type": "null"
        }
      ]
    },
    "employment_status": {
      "anyOf": [
        {
          "$ref": "#/$defs/EmploymentStatus"
        },
        {
          "type": "null"
        }
      ]
    },
    "external_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Your own identifier for this person, if you set one. Unique among the people your workspace owns. Always null on a `platform` person: the shared library is nobody's to label.",
      "title": "External Id"
    },
    "gender": {
      "anyOf": [
        {
          "$ref": "#/$defs/Gender"
        },
        {
          "type": "null"
        }
      ]
    },
    "generation_job_id": {
      "anyOf": [
        {
          "format": "uuid",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "The generation job that produced this person, when one did. This is how you collect a job's results: list people filtered by it.",
      "title": "Generation Job Id"
    },
    "household": {
      "anyOf": [
        {
          "$ref": "#/$defs/Household"
        },
        {
          "type": "null"
        }
      ]
    },
    "id": {
      "format": "uuid",
      "title": "Id",
      "type": "string"
    },
    "income_level": {
      "anyOf": [
        {
          "$ref": "#/$defs/IncomeLevel"
        },
        {
          "type": "null"
        }
      ]
    },
    "interests": {
      "description": "IAB taxonomy node ids this person is tagged with. Filterable via the `qualification` rule source, where a parent node also matches everyone tagged at a node beneath it.",
      "items": {
        "type": "string"
      },
      "title": "Interests",
      "type": "array"
    },
    "locale_type": {
      "anyOf": [
        {
          "$ref": "#/$defs/LocaleType"
        },
        {
          "type": "null"
        }
      ]
    },
    "name": {
      "description": "The person's display name.",
      "title": "Name",
      "type": "string"
    },
    "occupation": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Free-text job title, as written on the person.",
      "title": "Occupation"
    },
    "occupation_code": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Canonical ESCO/ISCO code beside the free-text `occupation`. Codes are hierarchical, so a `starts_with` filter on a group prefix selects a whole occupational family.",
      "title": "Occupation Code"
    },
    "owner": {
      "description": "`self` for a person your workspace owns; `platform` for one published in the shared ish library. Both are usable in a session; only `self` rows are yours to edit.",
      "enum": [
        "self",
        "platform"
      ],
      "title": "Owner",
      "type": "string"
    },
    "type": {
      "const": "ai",
      "default": "ai",
      "description": "Always `ai` on this API. ish also models real people who have consented to participate, and they are never readable here or through any credential you can mint. Treat this as an open union and tolerate a value you do not recognize.",
      "title": "Type",
      "type": "string"
    },
    "updated_at": {
      "format": "date-time",
      "title": "Updated At",
      "type": "string"
    },
    "workspace_id": {
      "anyOf": [
        {
          "format": "uuid",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "The owning workspace, present only when `owner` is `self`. A `platform` person belongs to no workspace, so this is null rather than naming one.",
      "title": "Workspace Id"
    }
  },
  "required": [
    "id",
    "name",
    "owner",
    "created_at",
    "updated_at"
  ],
  "type": "object",
  "$defs": {
    "EducationLevel": {
      "enum": [
        "less_than_secondary",
        "secondary",
        "some_post_secondary",
        "vocational_or_associate",
        "bachelor",
        "graduate"
      ],
      "title": "EducationLevel",
      "type": "string"
    },
    "EmploymentStatus": {
      "enum": [
        "employed_full_time",
        "employed_part_time",
        "self_employed",
        "unemployed_seeking",
        "student",
        "homemaker",
        "retired",
        "unable_to_work",
        "other"
      ],
      "title": "EmploymentStatus",
      "type": "string"
    },
    "Gender": {
      "description": "Gender options for people.",
      "enum": [
        "male",
        "female",
        "non-binary",
        "prefer_not_to_say"
      ],
      "title": "Gender",
      "type": "string"
    },
    "Household": {
      "enum": [
        "single",
        "couple_no_kids",
        "couple_with_kids",
        "single_parent",
        "shared_housing",
        "adult_with_parents",
        "multi_generational"
      ],
      "title": "Household",
      "type": "string"
    },
    "IncomeLevel": {
      "enum": [
        "lower",
        "lower_middle",
        "middle",
        "upper_middle",
        "upper",
        "prefer_not_to_say"
      ],
      "title": "IncomeLevel",
      "type": "string"
    },
    "LocaleType": {
      "enum": [
        "urban",
        "suburban",
        "small_town",
        "rural"
      ],
      "title": "LocaleType",
      "type": "string"
    }
  }
}