技術ドキュメント

Xenkey 仕様 v1.0

Xenkeyの権威ある読みやすい仕様 spec=1.0. スキーマ、意味モデル、ライフサイクル規則、インデックス、技術的挙動。

セクション 1

Xenkeyとは？

Xenkeyは現実世界の対象—ビジネス、製品、サービス、場所、人、プロセス、イベント—についての原子レベルの意味単位です。マーケティングの説得ではなく、AIの理解のために書かれています。

各Xenkeyは単一の最小・反証可能なアイデアを表します。仕様バージョンは各ドキュメントに宣言されます：

スキーマヘッダ
{ "spec": "1.0" }
セクション 2

設計目標

説得より真実

宣伝ではなく現実を記述する。

文脈性

いつ、どこで、誰に適用されるかを捉える。

合成可能性

多数のXenkeyで一つの対象を記述する。

AI可読性

検索とインデックスのための厳格な構造。

セクション 3

識別

項目型説明
idstring主識別子。形式：xk_ + ULID
ulidstring任意。idのサフィックスから導出（存在する場合は一致が必要）
spec"1.0"仕様バージョン
セクション 4

ライフサイクルと可変性

Xenkeyはデータの整合性と信頼性を保証する厳密なライフサイクルに従います。

ステータス:
draftunpublishedpublishedarchived

可変性ルール

  • •Draft — 自由に編集可能
  • •Published — 不変。変更には新しいXenkeyが必要
  • •もし published_at が設定されている場合、ステータスは draft
項目型説明
statusenumdraft | unpublished | published | archived
created_atdatetime作成タイムスタンプ（RFC 3339）
published_atdatetimeXenkeyが公開された時刻
updated_atdatetime内部/読み取り専用、APIが設定
etagstring内部/読み取り専用、同時実行制御用
セクション 5

意味コア

Xenkeyの心臓部。構造化された真実を捉える4つの必須フィールド。

項目型説明
titlestring体験の短く記述的な識別子
factstring現実に関する事実で検証可能な記述
meaningstringこの事実が人にとってなぜ重要か
contextstringいつ、どこで、誰に適用されるか
constraintsstring構造化フィールドで捉えられない自由記述のニュアンス
セクション 6

スコープとアンカー

アンカーはXenkeyを現実のエンティティに結び付けます。各Xenkeyは少なくとも1つのアンカーを持つ必要があります。マルチアンカー対応により、複数オブジェクトの交差を記述できます。

項目型説明
organization_idstring所有組織
base_idstring論理グルーピング（ワークスペース/プロジェクト）
unit_idstring構造化入力エントリへの任意参照
anchors[]arrayアンカーオブジェクトの配列（最小1）
アンカーオブジェクト
{
  "anchor_id": "anchor_001",
  "anchor_type": "product",
  "role": "primary"
}
アンカータイプ:
productservicepersonlocationeventprocessresource
セクション 7

タグ・感情・バイブ

項目型説明
tagsstring[]分類タグ（例：booking_required, wifi）
emotionsstring[]感情コンテキストコード（emotion-codes.json）
vibestring雰囲気/ムードの記述
seasonsstring[]適用季節
time_of_daystring[]適用時間帯
mealstring[]適用食事時間
季節:
springsummerautumnwinterall_yearholidaynew_yearchristmasorient_new_year
時間帯:
all_dayearly_morningmorningnoonafternooneveningnightlate_night
食事:
breakfastbrunchlunchdinnersuppertea_timecoffee_timesnack_time
セクション 8

デモグラフィック

項目型説明
age_mininteger推奨最小年齢
age_maxinteger推奨最大年齢（age_min以上）
genderstring対象性別（該当する場合）
セクション 9

地理

Xenkeyはグローバルにも地理的にも適用できます。フィールド geo_scope が必要な地理フィールドを決定します。

地理スコープ:
globalcountryregionpoint
項目型説明
geo_scopeenum地理精度レベル
countrystringISO 3166-1 alpha-2 国コード
regionstring地域/州/県
citystring都市名
timezonestringIANA タイムゾーン（例：Europe/Rome）
geo[lng, lat]座標 [経度, 緯度]
availability_countriesstring[]利用可能な国（場所ではない）

スコープルール： もし geo_scope=country なら country が必須。 もし geo_scope=region なら country と region (or city) が必須。 もし geo_scope=point なら geo が必須。

セクション 10

ローカリゼーション

項目型説明
localestring言語タグ（例：en-US, ja-JP）
source_localestringコンテンツの元言語
translation_groupstring翻訳をグループ化。形式：tg_ + ULID
is_source_localeboolean元言語版であれば true

ルール： もし is_source_locale = true, なら locale は source_locale. と同一である必要があります。翻訳は同じ translation_group を使用します。

セクション 11

整合性

公開されたXenkeyには公開時に計算された暗号学的ハッシュが含まれ、内容の整合性を保証します。

項目型説明
hash_alg"sha256"使用するハッシュアルゴリズム
hash_idstring一意なハッシュID。形式：hash_ + ULID
hashstring正規化ペイロードのSHA-256ハッシュ
セクション 12

インデックスとプライバシー

Xenkeyは複数のチャネルに公開できます。各チャネルは異なる検索機能を提供します。

項目型説明
publicationstring[]チャネル：vector, graph, aidex
is_publishedboolean少なくとも1チャネルに公開されていれば true
is_vectorbooleanベクトルストアに索引（Qdrant）
is_graphboolean知識グラフに投影（Neo4j）
is_aidexbooleanロボット指向のWiki層 Aidex に公開
is_privateboolean組織スコープのみ閲覧可能

ルール：

  • • aidex は vector を要求（publicationに両方必要）
  • • もしis_published=true なら publication に少なくとも1つのエントリが必要
  • • Aidexはベクトル索引より厳しいクォータを持つロボット指向のWiki層
セクション 13

ベクトル／グラフ検索

公開されたXenkeyは自動的に二つの補完的データ表現へ変換され、AIのハイブリッド検索を可能にします。

ベクトルインデックス（Qdrant）

  • • テキストソース：fact + meaning + context
  • • 高次元埋め込みに変換
  • • 意味的類似検索を可能にする
  • • ペイロードフィルタ：status, geo, tags, emotions, time
  • • 冪等性：キー（id, version）

知識グラフ（Neo4j）

  • • ノード：Xenkey, Organization, Object, Tag, Emotion
  • • エッジ：OWNS, DESCRIBED_BY, TAGS, EXPRESSES
  • • 関係と構造を可視化
  • • 自然キーでの冪等MERGE
  • • グラフ探索クエリを可能にする

ハイブリッド検索 はベクトル類似とグラフ構造フィルタを組み合わせ、根拠のある説明可能なAI回答を可能にします。 インデックスパイプラインはリトライとデッドレターキューを備えた非同期処理です。

セクション 14

不変条件

  • ✓anchors は必須で空であってはならない
  • ✓もしage_min と age_max があるなら age_max >= age_min
  • ✓もしgeo があるなら [longitude, latitude] であること
  • ✓geo_scope=country は country を要求
  • ✓geo_scope=region は country + region (or city) を要求
  • ✓geo_scope=point は geo を要求
  • ✓aidex が publication にある場合は vector も必要
  • ✓is_published=true は publication[] 非空 を要求
セクション 15

サンプルペイロード

ドラフトXenkey（最小）

draft-xenkey.json
{
  "spec": "1.0",
  "id": "xk_01J8Y6S4V9ZQ3M9K2W2M8JQY5C",
  "status": "draft",
  "created_at": "2026-01-21T12:00:00Z",
  "organization_id": "org_123",
  "base_id": "base_123",
  "anchors": [
    { "anchor_id": "anchor_1", "anchor_type": "product", "role": "primary" }
  ],
  "title": "Fresh espresso",
  "fact": "A 30 ml espresso shot made from 100% Arabica beans.",
  "meaning": "Represents the cafe's standard espresso offering.",
  "context": "Default menu item available all day.",
  "locale": "en-US",
  "source_locale": "en-US",
  "translation_group": "tg_01J8Y6S6Q4K8FKJ1PS2H0WQ1B8",
  "is_source_locale": true,
  "hash_alg": "sha256",
  "hash_id": "hash_01J8Y6S6Q4K8FKJ1PS2H0WQ1B9",
  "hash": "6e4f8c9d8b0f7a6d3b3a0f3c1f8e9d6e...",
  "is_vector": false,
  "is_graph": false,
  "is_aidex": false,
  "publication": [],
  "is_published": false,
  "is_private": false
}

公開Xenkey（geo + ベクトル索引）

published-xenkey.json
{
  "spec": "1.0",
  "id": "xk_01J8Y6S9QH8P2G8P6X1K3R2H5A",
  "status": "published",
  "created_at": "2026-01-21T12:05:00Z",
  "published_at": "2026-01-21T12:10:00Z",
  "organization_id": "org_123",
  "base_id": "base_123",
  "unit_id": "unit_456",
  "anchors": [
    { "anchor_id": "anchor_1", "anchor_type": "product", "role": "primary" }
  ],
  "title": "Fresh espresso",
  "fact": "A 30 ml espresso shot made from 100% Arabica beans.",
  "meaning": "Represents the cafe's standard espresso offering.",
  "context": "Default menu item available all day.",
  "tags": ["coffee", "espresso", "menu_item"],
  "time_of_day": ["morning", "afternoon"],
  "meal": ["breakfast", "coffee_time"],
  "vibe": "energetic",
  "geo_scope": "point",
  "country": "IT",
  "city": "Milan",
  "timezone": "Europe/Rome",
  "geo": [9.1900, 45.4642],
  "locale": "en-US",
  "source_locale": "en-US",
  "translation_group": "tg_01J8Y6S6Q4K8FKJ1PS2H0WQ1B8",
  "is_source_locale": true,
  "hash_alg": "sha256",
  "hash_id": "hash_01J8Y6S6Q4K8FKJ1PS2H0WQ1B9",
  "hash": "6e4f8c9d8b0f7a6d3b3a0f3c1f8e9d6e...",
  "is_vector": true,
  "is_graph": false,
  "is_aidex": false,
  "publication": ["vector"],
  "is_published": true,
  "is_private": false
}

この仕様はXenkeyの正準リファレンスです spec=1.0.

正準JSONスキーマ： xenkey_schema_v1_0.json