Xenkey Specification v1.0 — Technical Documentation

Раздел 1

Что такое Xenkey?

Xenkey — атомарная единица смысла о реальном объекте — бизнесе, продукте, сервисе, месте, человеке, процессе или событии. Он написан для понимания ИИ, а не для маркетингового убеждения.

Каждый Xenkey представляет одну минимальную, проверяемую идею. Версия спецификации указывается в каждом документе:

заголовок схемы

{ "spec": "1.0" }

Раздел 2

Цели дизайна

Правда вместо убеждения

Опишите реальность, а не продвижение.

Контекстность

Фиксируйте когда, где и для кого это применимо.

Композиционность

Многие Xenkey описывают один объект.

Читаемость для ИИ

Строгая структура для поиска и индексации.

Раздел 3

Идентичность

Поле	Тип	Обязательно	Описание
id	string	Да	Основной идентификатор. Формат: xk_ + ULID
ulid	string	Нет	Опционально. Производен от суффикса id (должен совпадать, если указан)
spec	"1.0"	Да	Версия спецификации

Раздел 4

Жизненный цикл и изменяемость

Xenkey следует строгому жизненному циклу, обеспечивающему целостность данных и доверие.

Статусы:

draftunpublishedpublishedarchived

Правила изменяемости

•Черновик — можно свободно редактировать
•Опубликован — неизменяемый. Изменения требуют нового Xenkey
•Если published_at задан, статус не может быть draft

Поле	Тип	Обязательно	Описание
status	enum	Да	draft \| unpublished \| published \| archived
created_at	datetime	Да	Время создания (RFC 3339)
published_at	datetime	Нет	Когда Xenkey был опубликован
updated_at	datetime	Нет	Внутреннее/только чтение, задаётся API
etag	string	Нет	Внутреннее/только чтение, контроль конкурентности

Раздел 5

Смысловое ядро

Сердце каждого Xenkey. Четыре обязательных поля, фиксирующие структурированную единицу правды.

Поле	Тип	Обязательно	Описание
title	string	Да	Короткий описательный идентификатор опыта
fact	string	Да	Фактическое, проверяемое утверждение о реальности
meaning	string	Да	Почему этот факт важен для людей
context	string	Да	Когда, где и для кого это применимо
constraints	string	Нет	Свободные нюансы, не отражённые в структурных полях

Раздел 6

Область и якоря

Якоря привязывают Xenkey к реальным сущностям. Каждый Xenkey должен иметь хотя бы один якорь. Поддержка нескольких якорей позволяет одному Xenkey описывать пересечение нескольких объектов.

Поле	Тип	Обязательно	Описание
organization_id	string	Да	Организация‑владелец
base_id	string	Да	Логическая группа (workspace/project)
unit_id	string	Нет	Опциональная ссылка на запись в структурных данных
anchors[]	array	Да	Массив объектов‑якорей (минимум 1)

объект якоря

{
  "anchor_id": "anchor_001",
  "anchor_type": "product",
  "role": "primary"
}

Типы якорей:

productservicepersonlocationeventprocessresource

Раздел 7

Теги, эмоции и вайб

Поле	Тип	Обязательно	Описание
tags	string[]	Нет	Классификационные теги (например, booking_required, wifi)
emotions	string[]	Нет	Коды эмоционального контекста (из emotion-codes.json)
vibe	string	Нет	Описание атмосферы / настроения
seasons	string[]	Нет	Применимые сезоны
time_of_day	string[]	Нет	Применимое время суток
meal	string[]	Нет	Применимые приёмы пищи

Сезоны:

springsummerautumnwinterall_yearholidaynew_yearchristmasorient_new_year

Время суток:

all_dayearly_morningmorningnoonafternooneveningnightlate_night

Приём пищи:

breakfastbrunchlunchdinnersuppertea_timecoffee_timesnack_time

Раздел 8

Демография

Поле	Тип	Обязательно	Описание
age_min	integer	Нет	Минимальный рекомендуемый возраст
age_max	integer	Нет	Максимальный рекомендуемый возраст (должен быть >= age_min)
gender	string	Нет	Целевая гендерная аудитория (если применимо)

Раздел 9

География

Xenkey может быть глобальным или гео‑ограниченным. Поле geo_scope определяет, какие географические поля обязательны.

Гео‑области:

globalcountryregionpoint

Поле	Тип	Обязательно	Описание
geo_scope	enum	Нет	Уровень географической точности
country	string	Нет	Код страны ISO 3166-1 alpha-2
region	string	Нет	Регион / штат / провинция
city	string	Нет	Название города
timezone	string	Нет	Название часового пояса IANA (например, Europe/Rome)
geo	[lng, lat]	Нет	Координаты как [долгота, широта]
availability_countries	string[]	Нет	Страны, где это доступно (не местоположение)

Правила области: Если geo_scope=country то country обязателен. Если geo_scope=region то country и region (or city) обязательны. Если geo_scope=point то geo обязателен.

Раздел 10

Локализация

Поле	Тип	Обязательно	Описание
locale	string	Да	Языковой тег (например, en-US, ja-JP)
source_locale	string	Да	Исходный язык контента
translation_group	string	Да	Группирует переводы. Формат: tg_ + ULID
is_source_locale	boolean	Да	True, если это исходная языковая версия

Правило: Если is_source_locale = true, то locale должен совпадать с source_locale. Переводы используют ту же translation_group.

Раздел 11

Целостность

Опубликованные Xenkey включают криптографический хэш, вычисленный при публикации, что обеспечивает целостность контента.

Поле	Тип	Обязательно	Описание
hash_alg	"sha256"	Да	Используемый алгоритм хэширования
hash_id	string	Да	Уникальный идентификатор хэша. Формат: hash_ + ULID
hash	string	Да	SHA-256 хэш канонического payload

Раздел 12

Индексация и приватность

Xenkey может публиковаться в нескольких каналах. Каждый канал включает разные возможности извлечения.

Поле	Тип	Обязательно	Описание
publication	string[]	Нет	Каналы: vector, graph, aidex
is_published	boolean	Нет	True, если опубликован хотя бы в одном канале
is_vector	boolean	Нет	Индексируется в векторном хранилище (Qdrant)
is_graph	boolean	Нет	Проецируется в граф знаний (Neo4j)
is_aidex	boolean	Нет	Опубликован в Aidex robot‑oriented wiki
is_private	boolean	Нет	Виден только в рамках организации

Правила:

• aidex требует vector (оба должны быть в publication)
• Еслиis_published=true publication должен содержать хотя бы одну запись
• Aidex — робот‑ориентированный слой wiki с более строгими квотами, чем векторная индексация

Раздел 13

Векторный и графовый поиск

Опубликованные Xenkey автоматически превращаются в две взаимодополняющие структуры данных, обеспечивая гибридный поиск для ИИ.

Векторный индекс (Qdrant)

• Источник текста:fact + meaning + context
• Преобразуется в высокоразмерные эмбеддинги
• Обеспечивает семантический поиск по сходству
• Фильтры payload: status, geo, tags, emotions, time
• Идемпотентность: ключ (id, version)

Граф знаний (Neo4j)

• Узлы: Xenkey, Organization, Object, Tag, Emotion
• Рёбра: OWNS, DESCRIBED_BY, TAGS, EXPRESSES
• Показывает связи и структуру
• Идемпотентный MERGE по естественным ключам
• Позволяет выполнять графовые запросы

Гибридный поиск сочетает векторное сходство со структурными фильтрами графа, обеспечивая обоснованные и объяснимые ответы ИИ. Индексационный конвейер асинхронный, с повторами и очередями dead-letter.

Раздел 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 в publication
✓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 (с гео + векторной индексацией)

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

Спецификация Xenkey v1.0