neo4j-ontology-skill

适用场景

• 根据领域描述编写本体文档（Neo4j 本体图规范）
• 编辑现有本体 YAML/JSON：节点、关系、属性、类型、约束、基数、扩展
• 根据规范架构验证本体文档

不适用场景

• Cypher 查询，或将本体加载/应用到数据库中 → neo4j-cypher-skill（本体 Cypher 过程目前尚不存在——后续会处理）
• 通用图建模建议（节点与属性或标签的选择、反模式、超级节点） → neo4j-modeling-skill

---

编写工作流

第 1 步 — 收集领域意图

确定要建模的内容：实体类型（节点）、连接（关系 + 方向）、每个元素的属性、标识键、必填字段、基数。如果领域或所需结构不明确，请询问用户要建模什么，以及本体必须回答哪些问题。不要猜测领域。

第 2 步 — 起草文档

根据用户偏好使用 YAML 或 JSON；默认使用 YAML（可读性更高）。应用下方的核心事实。当需要最简示例之外的内容时，加载 references/format-reference.md（完整的 labels 对象、约束对象、扩展、完整的数据类型语法）。

第 3 步 — 验证

# From the skill directory:
uv run scripts/validate.py <document.{yaml,yml,json}>
# From the repo root:
uv run neo4j-ontology-skill/scripts/validate.py <document.{yaml,yml,json}>

退出码 0 = 有效 · 退出码 1 = 架构违规（每个字段路径占一行） · 退出码 2 = 解析/读取/获取错误。PEP 723 脚本——uv 会自行解析依赖（jsonschema、pyyaml）。

验证器会实时获取架构——不会将其随附存储。解析顺序：--schema <path-or-url>（显式指定，不回退）→ 文档自身的 schema 字段（当其为 URL 时）→ 已发布的 current 别名 → 过渡期仓库原始地址回退。文档中的 schema URL 决定验证所依据的版本：将其设为正在编写版本的已发布版本化 URL（较旧版本会根据其已发布的架构进行验证）。

第 4 步 — 修复并重新验证

修复所有报告的错误；重新运行第 3 步。重复执行，直到退出码为 0。验证是强制要求——退出码非 0 时，绝不能将本体作为已完成内容提交。

---

核心事实

• 必需的根字段：schema、id（唯一的本体 ID 字符串）、version（字符串——用户定义的修订标签；在 YAML 中用引号括起来：version: "1"）。根对象会拒绝未知字段（additionalProperties: false）。
• schema 的值：正在编写版本的已发布 URL，例如 https://neo4j.com/docs/ontology-graph-spec/1.0.0/schema.json。根键是普通的 schema，不是 $schema。
• nodes / relationships 是以本地 ID 为键的映射，而不是以标签/类型为键。标签位于 label 或 labels.identifier 中；关系类型位于 type 中。端点引用节点 ID（from.node / to.node）——重命名标签不会破坏引用。
• label: X 是 labels: {identifier: X} 的简写。只有存在 implied 或 optional 标签时，才使用完整的 labels 对象。
• 类型标记必须严格使用 Neo4jType 枚举中的值——区分大小写。标记包括 STRING、INTEGER、FLOAT、BOOLEAN、DATE、DURATION、POINT、UUID；时间类型标记中含有空格（ZONED DATETIME、LOCAL TIME）；参数化标记使用尖括号（LIST<STRING>、VECTOR<FLOAT32>）。UUID 和 VECTOR<...> 没有 LIST 分支。不支持联合类型和嵌套列表。dimension（整数或 null）位于属性上，并与 VECTOR 类型配对。
• 约束——有两种形式：
  • 属性上的标记：key: true、unique: true、must_exist: true（snake_case——不是 mustExist）。用于单属性的简写；根据 Neo4j 键约束语义，key = 唯一 + 存在。
  • 对象形式：constraints 是一个映射，键为 ID，值为约束对象 {type: EXISTS|KEY|PROPERTY_TYPE|UNIQUE, properties: [p1, ...], name: optional}——复合约束（≥ 2 个属性）和可命名约束必须使用此形式。properties 必须列出在同一元素上声明的属性。
• 端点基数：使用 count 表示精确值，或使用 min_count/max_count 表示范围；缺省表示不受约束（0..*）。
• 扩展：每种元素都有固定的 extensions 结构——节点：indexes/display/custom；关系：indexes/custom；根对象：tables/mappings/custom；标签/属性/约束/索引：仅 custom。未知的扩展键会被拒绝。custom 为自由格式——可存放任意所有者数据，规范 schema 永远不会对其进行验证。
• 缺省表示无——绝不要写空映射/列表（properties: {}、aliases: []、custom: {}）；直接省略。

最小示例

library.ontology.yaml — 2 个节点、1 个关系：

schema: "https://neo4j.com/docs/ontology-graph-spec/1.0.0/schema.json"
id: library
version: "1"
name: Library
nodes:
  author:
    label: Author
    properties:
      id: { type: STRING, key: true }
      name: { type: STRING, must_exist: true }
  book:
    label: Book
    properties:
      isbn: { type: STRING, key: true }
relationships:
  wrote:
    type: WROTE
    from: { node: author, max_count: 1 }
    to: { node: book }

通过 scripts/validate.py 验证时退出码为 0。完整的 YAML+JSON 示例见 references/format-reference.md。

---

参考资料

按需加载：

• references/format-reference.md — 完整字段参考：所有节点/关系/属性/端点字段、labels 对象、约束对象、扩展结构、数据类型语法、注意事项以及 YAML+JSON 示例
• 已发布 schema 基础 URL：https://neo4j.com/docs/ontology-graph-spec/ — 每个规范版本对应不可变的 /<version>/schema.json，另有动态别名 /current/schema.json

规范状态

已发布：上述 ONT-31 URL 已生效，是规范 schema 的权威来源。如果已发布的主机无法访问，验证器会回退到 neo4j/ontology-graph-spec main 中的原始 schema（动态版本）。Ontology Cypher 过程尚不存在；将本体应用到数据库不在本文范围内。

---

检查清单

• 存在根字段 schema、id、version；version 是带引号的字符串；schema = plain schema 键下发布的版本化 URL
• 没有未知根字段；没有 $schema
• nodes/relationships 以本地 ID 为键；关系的 from/to 引用节点 ID
• 每个节点都有 label 或 labels.identifier
• 类型标记与 Neo4jType 枚举完全一致（区分大小写；时间类型标记中有空格）；VECTOR 类型的属性需设置 dimension
• 标志仅用于单属性约束；复合约束/命名约束使用对象形式（type ∈ EXISTS/KEY/PROPERTY_TYPE/UNIQUE）；约束的 properties 在同一元素上存在
• 扩展键与元素的固定结构相符；任意数据只能放在 custom 下
• 不写空映射/列表
• uv run scripts/validate.py <file> 的退出码为 0（修复每个报告的错误并重新验证）