Validation Contract

JSON Schema

Schema 负责把“页面大概长这样”变成“页面必须长这样”。它让数据验证、生成工具和索引管道能共享同一合同。

Schema 目标

Schema 的价值不在于字段越多越好，而在于让关键字段足够稳定、足够明确。

保证每个页面对象都带核心身份字段与更新时间。
保证每个 section 有独立 id、标题、摘要和正文数组。
限制随意扩展字段，减少不同页面结构漂移。
让索引系统能在不知道 HTML 结构的前提下消费正文。

核心字段

最低限度上，一个页面 JSON 至少要回答“它是谁、从哪里来、有什么内容、何时更新”。

字段	类型	作用
`id`	string	页面稳定标识，与 slug 对齐。
`url`	string	HTML 页面地址。
`rawUrl` / `apiUrl`	string	Markdown 与 JSON 自引用地址。
`title` / `summary`	string	人类和模型都可以直接消费的最短描述。
`lastUpdated` / `version`	string	新鲜度与兼容性信号。
`sections`	array	正文主载体，按 section 提供稳定 chunk。

Section 对象结构

section 是最重要的检索单元，所以需要比页面顶层更严格的约束。

{
  "id": "required-fields",
  "title": "核心字段",
  "summary": "说明页面对象中必须保留的字段。",
  "content": [
    "id 是页面稳定标识，与 slug 对齐。",
    "sections 数组承载正文主内容。"
  ]
}

Schema 文件

实际校验合同保存在独立 schema 文件中，而不是只存在说明文档里。

主 schema 文件：https://pingfanfan.github.io/OpenWebsite/schema/knowledge-page.schema.json

站点索引文件：https://pingfanfan.github.io/OpenWebsite/api/site.json