{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "历史人物数据规范",
  "description": "每个人物一个 JSON 文件，存于 data/persons/。年份用整数表示，公元前为负数（如前202年 = -202）；不详则为 null。所有内容须基于史实自拟文字，禁止照抄现代出版物。",
  "type": "object",
  "required": [
    "id",
    "name",
    "role",
    "summary",
    "bio_events",
    "sources"
  ],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^[a-z0-9-]+$",
      "description": "拼音小写连字符，如 liu-bang；与文件名一致（liu-bang.json）"
    },
    "name": {
      "type": "string",
      "description": "姓名，如 刘邦"
    },
    "courtesy_name": {
      "type": [
        "string",
        "null"
      ],
      "description": "字，如 季；无或不详为 null"
    },
    "title": {
      "type": [
        "string",
        "null"
      ],
      "description": "谥号/称号，如 汉高祖、西楚霸王"
    },
    "aliases": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "别名/号/俗称/异体写法（如 管仲、齐宣王、项籍、朱全忠、曾国籓），搜索索引与提及统计用。规则见规范 §2.3：只收史料中确实出现、且指向明确无歧义的称呼；与 name/courtesy_name/title 重复的值不收（build.py 会警告）；当前可不填"
    },
    "birth_year": {
      "type": [
        "integer",
        "null"
      ],
      "description": "生年，公元前为负；不详为 null"
    },
    "birth_year_approx": {
      "type": "boolean",
      "description": "生年为推断或有疑义时 true（显示为「约前X年」）；有明确史料记载时省略或 false。year 为 null 时不得设置此字段"
    },
    "death_year": {
      "type": [
        "integer",
        "null"
      ],
      "description": "卒年，公元前为负；不详为 null"
    },
    "death_year_approx": {
      "type": "boolean",
      "description": "卒年为推断或有疑义时 true；规则同 birth_year_approx"
    },
    "birthplace": {
      "type": [
        "string",
        "null"
      ],
      "description": "籍贯，古地名+今地名"
    },
    "activity_areas": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "古地名+今地名，如 邺城（今河北临漳）"
      },
      "description": "主要活动地点（籍贯除外），2-5 个，按重要性排序：常年治所、为官/驻军地、重大事件发生地。为地域关联检索预留，当前可不填"
    },
    "role": {
      "type": "string",
      "enum": [
        "帝王",
        "诸侯",
        "武将",
        "文臣",
        "文人",
        "后宫",
        "宗室",
        "其他"
      ],
      "description": "主身份（单值，图谱着色/卡片显示用）。文人=以文学/学术/艺术/科技成就为主要历史定位者。多身份用 roles 叠加，不强行二选一"
    },
    "roles": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "帝王",
          "诸侯",
          "武将",
          "文臣",
          "文人",
          "后宫",
          "宗室",
          "其他"
        ]
      },
      "description": "身份全集（筛选/朝代分榜用），须包含 role。缺省视为 [role]。叠加示例：苏轼=[文臣,文人]（以仕宦为主身份、文学成就并列）；曹雪芹 role 由其他改为文人"
    },
    "groups": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "并称/名号归属(如 竹林七贤/曹魏五子良将/太康二陆)，非个人关系；标注前提=全部成员已入库且并称有出处"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "受控标签，如 改革家、名将、医学、经学；集合由规范维护，不允许自由发挥"
      },
      "description": "人物标签（专题页筛选用），受控集合，当前可不填"
    },
    "summary": {
      "type": "string",
      "description": "人物简介，100字以内，自拟"
    },
    "bio_events": {
      "type": "array",
      "description": "生平大事，按时间排序",
      "items": {
        "type": "object",
        "required": [
          "year",
          "event"
        ],
        "properties": {
          "year": {
            "type": [
              "integer",
              "null"
            ],
            "description": "年份；时间不详为 null"
          },
          "year_approx": {
            "type": "boolean",
            "description": "本条系年为推断或有疑义时 true（如由「年八十二」与卒年反推、由背景事件系年）；有明确系年史料时省略或 false。year 为 null 时不得设置此字段"
          },
          "event": {
            "type": "string",
            "description": "事件描述，一句话"
          },
          "location": {
            "type": [
              "string",
              "null"
            ],
            "description": "事件发生地，古地名+今地名对照；不明确则省略。为地图维度预留"
          },
          "note": {
            "type": "string",
            "description": "异说/存疑注记。其他来源与本条记载不一致时写明，如「《汉书》系此事于元鼎六年，与本纪异」；不擅自二选一"
          },
          "posthumous": {
            "type": "boolean",
            "description": "身后事标记：事件发生在人物卒年之后（如身后平反、追赠、余党败亡），系年为事件实际发生年，置 true 后 build.py 不再报「晚于卒年」警告；event 文本中应同时写明「身后」语境"
          },
          "sources": {
            "type": "array",
            "items": {
              "oneOf": [
                {
                  "type": "string",
                  "description": "书级简写，默认原始史料，如 《后汉书·班超传》"
                },
                {
                  "type": "object",
                  "required": [
                    "text"
                  ],
                  "properties": {
                    "text": {
                      "type": "string"
                    },
                    "tier": {
                      "type": "string",
                      "enum": [
                        "原始史料",
                        "出土文献",
                        "后世研究",
                        "百科网络"
                      ]
                    },
                    "url": {
                      "type": "string"
                    }
                  }
                }
              ]
            },
            "description": "本条事件的书级出处（如《后汉书·班超传》，不必精确到卷）。省略表示出自人物级 sources 的骨架史料；第二遍丰富资料时新增/修订的事件必填"
          }
        }
      }
    },
    "evaluations": {
      "type": "array",
      "description": "历代评价（为第二遍丰富资料预留，当前可不填）",
      "items": {
        "type": "object",
        "required": [
          "text",
          "source"
        ],
        "properties": {
          "text": {
            "type": "string",
            "description": "评价原文摘录或概述，如太史公曰、后世史家评论"
          },
          "source": {
            "type": "string",
            "description": "书级出处，如 《史记·高祖本纪》赞语"
          }
        }
      }
    },
    "sources": {
      "type": "array",
      "items": {
        "oneOf": [
          {
            "type": "string",
            "description": "简写形式，默认视为原始史料，如 《史记·高祖本纪》"
          },
          {
            "type": "object",
            "required": [
              "text"
            ],
            "properties": {
              "text": {
                "type": "string"
              },
              "tier": {
                "type": "string",
                "enum": [
                  "原始史料",
                  "出土文献",
                  "后世研究",
                  "百科网络"
                ],
                "description": "来源分级，缺省为 原始史料"
              },
              "url": {
                "type": "string",
                "description": "次级来源可附链接备查"
              }
            }
          }
        ]
      },
      "description": "史料出处。分级含义：原始史料=史记/汉书等同期文献；出土文献=简牍碑刻；后世研究=专著论文；百科网络=维基等，仅作线索。无一手史料的人物会在构建时给出警告，但允许入库。"
    }
  }
}