neo4j-ontology-skill

使用する場合

• ドメインの説明からオントロジー文書（Neo4j Ontology Graph Specification）を作成する場合
• 既存のオントロジー 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 = スキーマ違反（フィールドパスごとに 1 行） · 終了コード 2 = 解析／読み取り／取得エラー。PEP 723 スクリプト — uv が依存関係（jsonschema、pyyaml）を自動的に解決します。

バリデーターはスキーマをその都度取得します。スキーマは同梱されていません。解決順序：--schema <path-or-url>（明示指定、フォールバックなし）→ 文書の schema フィールドが URL の場合はその値 → 公開されている current エイリアス → 移行期間中のリポジトリ raw フォールバック。文書の schema URL により、検証対象のバージョンが決まります。作成中のバージョンの公開済みバージョン指定 URL を設定してください（古いバージョンは公開済みのスキーマに対して検証されます）。

ステップ 4 — 修正して再検証する

報告されたエラーをすべて修正し、ステップ 3 を再実行します。終了コード 0 になるまで繰り返します。検証は必須です。終了コードが 0 以外の状態で、オントロジーを完成品として提示してはいけません。

---

基本事項

• 必須のルートフィールド：schema、id（一意のオントロジー ID 文字列）、version（STRING — ユーザー定義の改訂ラベル。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 enum の値を大文字・小文字も含めて正確に使用します。トークンには STRING、INTEGER、FLOAT、BOOLEAN、DATE、DURATION、POINT、UUID があります。時間関連のトークンにはスペースが含まれます（ZONED DATETIME、LOCAL TIME）。パラメーター付きトークンには山括弧を使用します（LIST<STRING>、VECTOR<FLOAT32>）。UUID と VECTOR<...> には LIST の型はありません。ユニオン型やネストされたリストは使用できません。dimension（integer|null）はプロパティに指定し、VECTOR 型と組み合わせます。
• 制約 — 2 つの形式があります。
  • プロパティのフラグ：key: true、unique: true、must_exist: true（snake_case — mustExist ではありません）。単一プロパティ用の省略形です。Neo4j のキー制約のセマンティクスでは、key は unique + exists を意味します。
  • オブジェクト形式：constraints は、制約オブジェクト {type: EXISTS|KEY|PROPERTY_TYPE|UNIQUE, properties: [p1, ...], name: optional} に対応する MAP id → constraint object です。複合制約（2 つ以上のプロパティ）および名前を付けられる制約では必須です。properties には、同じ要素で宣言されたプロパティを指定する必要があります。
• エンドポイントのカーディナリティ：count は厳密な数、min_count / max_count は範囲を指定します。省略した場合は制約なし（0..*）です。
• 拡張：要素ごとに extensions の形式は固定です。ノード：indexes / display / custom、リレーションシップ：indexes / custom、ルート：tables / mappings / custom、ラベル／プロパティ／制約／インデックス：custom のみです。未知の拡張キーは拒否されます。custom は自由形式で、任意の所有者データを格納します。仕様スキーマによる検証は行われません。
• 省略は「なし」を意味します。空のマップやリスト（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 の例
• 公開スキーマのベース URL：https://neo4j.com/docs/ontology-graph-spec/ — 仕様バージョンごとに不変の /<version>/schema.json を提供し、移動するエイリアス /current/schema.json もあります。

仕様のステータス

公開済みです。上記の ONT-31 URL は現在有効で、正規のスキーマソースです。公開ホストに接続できない場合、バリデーターは neo4j/ontology-graph-spec の main にある raw スキーマ（移動します）にフォールバックします。オントロジー用の Cypher プロシージャはまだ存在しません。オントロジーをデータベースに適用することは、ここでは対象外です。

---

チェックリスト

• ルートフィールド schema、id、version が存在し、version は引用符で囲まれた文字列であること。schema は、通常の 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 で終了すること（報告されたエラーをすべて修正し、再検証すること）