SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场neo4j-ontology-skill

neo4j-ontology-skill

数据与分析

查看项目

更新于 10-22 01:23

技能介绍

用途

本技能用于编写和校验 Neo4j Ontology Graph Specification（本体图规范）文档。适用场景包括：

  • 根据领域描述撰写本体文档；
  • 编辑已有的本体 YAML/JSON，涉及节点、关系、属性、类型、约束、基数、扩展；
  • 依据规范 schema 校验本体文档。

不适用场景：

  • Cypher 查询，或将本体加载/应用到数据库 → 应使用 neo4j-cypher-skill（本体 Cypher 过程目前尚不存在，属于后续工作）；
  • 通用图建模建议（节点与属性与标签的取舍、反模式、超级节点）→ 应使用 neo4j-modeling-skill。

编写工作流

第 1 步 — 收集领域意图

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

第 2 步 — 起草文档

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

第 3 步 — 校验

# 从技能目录运行：
uv run scripts/validate.py <document.{yaml,yml,json}>
# 从仓库根目录运行：
uv run neo4j-ontology-skill/scripts/validate.py <document.{yaml,yml,json}>

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

校验器实时获取 schema——不内置任何副本。解析顺序：--schema <path-or-url>（显式指定，无回退）→ 文档自身的 schema 字段（当其为 URL 时）→ 已发布的 current 别名 → 过渡期的仓库 raw 回退。文档的 schema URL 决定其校验所依据的版本：应将其设置为正在编写版本的已发布版本化 URL（旧版本依据其已发布的 schema 校验）。

第 4 步 — 修复并重新校验

修复所有报告的错误；重新运行第 3 步。重复直至退出码为 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} 的简写。仅当存在隐含或可选标签时才使用完整 labels 对象。
  • 类型标记必须精确来自 Neo4jType 枚举——区分大小写。标记包括 STRING、INTEGER、FLOAT、BOOLEAN、DATE、DURATION、POINT、UUID；时间类标记含空格（ZONED DATETIME、LOCAL TIME）；参数化标记使用尖括号（LIST<STRING>、VECTOR<FLOAT32>）。UUID 和 VECTOR<...> 没有 LIST 分支。不支持联合类型，不支持嵌套列表。dimension（integer|null）位于属性上，与 VECTOR 类型配对使用。
  • 约束——两种形式：
    • 属性上的标志：key: true、unique: true、must_exist: true（snake_case——不是 mustExist）。单属性简写；按 Neo4j 键约束语义，key = unique + exists。
    • 对象形式：constraints 是 id → 约束对象的映射 {type: EXISTS|KEY|PROPERTY_TYPE|UNIQUE, properties: [p1, ...], name: 可选}——复合约束（≥ 2 个属性）和可命名约束必须使用此形式。properties 必须命名同一元素上声明的属性。
  • 端点基数：count 为精确值，或 min_count/max_count 为范围；缺省 = 不受约束（0..*）。
  • 扩展：每个元素的 extensions 形状固定——node：indexes/display/custom；relationship：indexes/custom；root：tables/mappings/custom；labels/property/constraint/index：仅 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 基础地址：https://neo4j.com/docs/ontology-graph-spec/——每个规范版本有不可变的 /<version>/schema.json，以及移动别名 /current/schema.json

规范状态

已发布：上述 ONT-31 URL 已上线，是规范的 schema 来源。如果已发布主机不可达，校验器会回退到 neo4j/ontology-graph-spec main 分支的 raw schema（移动）。本体 Cypher 过程目前尚不存在；将本体应用到数据库不在本技能范围内。

检查清单

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