Xenkey Specification v1.0 — Technical Documentation

섹션 1

Xenkey란?

Xenkey는 실제 세계 객체—비즈니스, 제품, 서비스, 장소, 사람, 프로세스, 이벤트—에 대한 원자 단위의 의미입니다. 마케팅 설득이 아니라 AI 이해를 위해 작성됩니다.

각 Xenkey는 하나의 최소·반증 가능한 아이디어를 나타냅니다. 사양 버전은 각 문서에 선언됩니다:

스키마 헤더

{ "spec": "1.0" }

섹션 2

설계 목표

설득보다 진실

홍보가 아닌 현실을 설명한다.

문맥성

언제, 어디서, 누구에게 적용되는지 포착한다.

조합 가능성

여러 Xenkey가 하나의 객체를 설명한다.

AI 가독성

검색과 인덱싱을 위한 엄격한 구조.

섹션 3

식별

필드	타입	필수	설명
id	string	예	주 식별자. 형식: xk_ + ULID
ulid	string	아니오	선택 사항. id 접미사에서 파생(있으면 일치해야 함)
spec	"1.0"	예	사양 버전

섹션 4

라이프사이클 및 변경 가능성

Xenkey는 데이터 무결성과 신뢰를 보장하는 엄격한 라이프사이클을 따릅니다.

상태:

draftunpublishedpublishedarchived

변경 가능성 규칙

•Draft — 자유롭게 수정 가능
•Published — 불변. 변경하려면 새로운 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의 심장. 구조화된 진실 단위를 담는 4개의 필수 필드.

필드	타입	필수	설명
title	string	예	경험을 요약하는 짧고 설명적인 식별자
fact	string	예	현실에 대한 사실적이고 검증 가능한 진술
meaning	string	예	이 사실이 사람들에게 왜 중요한지
context	string	예	언제, 어디서, 누구에게 적용되는지
constraints	string	아니오	구조화 필드로 포착되지 않는 자유 텍스트 뉘앙스

섹션 6

범위와 앵커

앵커는 Xenkey를 실제 엔티티에 연결합니다. 각 Xenkey는 최소 하나의 앵커가 있어야 합니다. 멀티 앵커 지원으로 여러 객체의 교차점을 설명할 수 있습니다.

필드	타입	필수	설명
organization_id	string	예	소유 조직
base_id	string	예	논리 그룹 (워크스페이스/프로젝트)
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	예	고유 해시 ID. 형식: hash_ + ULID
hash	string	예	정규화 페이로드의 SHA-256 해시

섹션 12

인덱싱 및 프라이버시

Xenkey는 여러 채널로 공개될 수 있습니다. 각 채널은 다른 검색 기능을 제공합니다.

필드	타입	필수	설명
publication	string[]	아니오	채널: vector, graph, aidex
is_published	boolean	아니오	최소 하나의 채널에 게시되면 true
is_vector	boolean	아니오	벡터 스토어에 인덱싱 (Qdrant)
is_graph	boolean	아니오	지식 그래프로 투영 (Neo4j)
is_aidex	boolean	아니오	로봇 지향 위키 계층 Aidex에 게시
is_private	boolean	아니오	조직 범위 접근에만 표시

규칙:

• aidex 는 vector 를 필요로 함 (publication에 둘 다 포함)
• 만약is_published=true 라면 publication에 최소 한 항목 필요
• Aidex는 벡터 인덱싱보다 더 엄격한 쿼터를 가진 로봇 지향 위키 계층

섹션 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

Xenkey 사양 v1.0