Xenkey Specification v1.0 — Technical Documentation

Section 1

What is a Xenkey?

A Xenkey is an atomic unit of meaning about a real-world object — a business, product, service, place, person, process, or event. It is written for AI understanding, not for marketing persuasion.

Each Xenkey represents a single, minimal, falsifiable idea. The specification version is declared in every document:

schema header

{ "spec": "1.0" }

Section 2

Design Goals

Truth over persuasion

Describe reality, not promotion.

Contextuality

Capture when, where, and for whom it applies.

Composability

Many Xenkeys describe one object.

AI readability

Strict structure for retrieval and indexing.

Section 3

Identity

Field	Type	Required	Description
id	string	Yes	Primary identifier. Format: xk_ + ULID
ulid	string	No	Optional. Derived from id suffix (must match if present)
spec	"1.0"	Yes	Specification version

Section 4

Lifecycle & Mutability

Xenkeys follow a strict lifecycle that ensures data integrity and trust.

Statuses:

draftunpublishedpublishedarchived

Mutability Rules

•Draft — can be edited freely
•Published — immutable. Changes require a new Xenkey
•If published_at is set, status cannot be draft

Field	Type	Required	Description
status	enum	Yes	draft \| unpublished \| published \| archived
created_at	datetime	Yes	Creation timestamp (RFC 3339)
published_at	datetime	No	When the Xenkey was published
updated_at	datetime	No	Internal/read-only, set by API
etag	string	No	Internal/read-only, used for concurrency control

Section 5

Meaning Core

The heart of every Xenkey. Four required fields that capture a structured unit of truth.

Field	Type	Required	Description
title	string	Yes	Short, descriptive identifier for the experience
fact	string	Yes	Factual, verifiable statement about reality
meaning	string	Yes	Why this fact matters to humans
context	string	Yes	When, where, and for whom this applies
constraints	string	No	Free-form nuance not captured by structured fields

Section 6

Scope & Anchors

Anchors tie Xenkeys to real-world entities. Every Xenkey must have at least one anchor. Multi-anchor support allows a single Xenkey to describe the intersection of multiple objects.

Field	Type	Required	Description
organization_id	string	Yes	Owning organization
base_id	string	Yes	Logical grouping (workspace/project)
unit_id	string	No	Optional structured data entry reference
anchors[]	array	Yes	Array of anchor objects (min 1)

anchor object

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

Anchor types:

productservicepersonlocationeventprocessresource

Section 7

Tags, Emotions & Vibe

Field	Type	Required	Description
tags	string[]	No	Classification tags (e.g., booking_required, wifi)
emotions	string[]	No	Emotional context codes (from emotion-codes.json)
vibe	string	No	Atmosphere / mood description
seasons	string[]	No	Applicable seasons
time_of_day	string[]	No	Applicable times of day
meal	string[]	No	Applicable meal periods

Seasons:

springsummerautumnwinterall_yearholidaynew_yearchristmasorient_new_year

Time of day:

all_dayearly_morningmorningnoonafternooneveningnightlate_night

Meal:

breakfastbrunchlunchdinnersuppertea_timecoffee_timesnack_time

Section 8

Demographics

Field	Type	Required	Description
age_min	integer	No	Minimum recommended age
age_max	integer	No	Maximum recommended age (must be >= age_min)
gender	string	No	Target gender (if applicable)

Section 9

Geography

Xenkeys can be global or geo-scoped. The geo_scope field determines which geographic fields are required.

Geo scopes:

globalcountryregionpoint

Field	Type	Required	Description
geo_scope	enum	No	Geographic precision level
country	string	No	ISO 3166-1 alpha-2 country code
region	string	No	Region / state / province
city	string	No	City name
timezone	string	No	IANA timezone name (e.g., Europe/Rome)
geo	[lng, lat]	No	Coordinates as [longitude, latitude]
availability_countries	string[]	No	Countries where this is available (not location)

Scope rules: If geo_scope=country, country is required. If region, both country and region (or city) are required. If point, geo is required.

Section 10

Localization

Field	Type	Required	Description
locale	string	Yes	Language tag (e.g., en-US, ja-JP)
source_locale	string	Yes	Original language of the content
translation_group	string	Yes	Groups translations together. Format: tg_ + ULID
is_source_locale	boolean	Yes	True if this is the original language version

Rule: If is_source_locale = true, then locale must equal source_locale. Translations reuse the same translation_group.

Section 11

Integrity

Published Xenkeys include a cryptographic hash computed at publish time, ensuring content integrity.

Field	Type	Required	Description
hash_alg	"sha256"	Yes	Hash algorithm used
hash_id	string	Yes	Unique hash identifier. Format: hash_ + ULID
hash	string	Yes	SHA-256 hash of the canonical payload

Section 12

Indexing & Privacy

Xenkeys can be published to multiple channels. Each channel enables different retrieval capabilities.

Field	Type	Required	Description
publication	string[]	No	Channels: vector, graph, aidex
is_published	boolean	No	True if published to at least one channel
is_vector	boolean	No	Indexed in vector store (Qdrant)
is_graph	boolean	No	Projected to knowledge graph (Neo4j)
is_aidex	boolean	No	Published to Aidex robot-oriented wiki
is_private	boolean	No	Visible only to org-scoped access

Rules:

• aidex requires vector (both must be in publication)
• If is_published=true, publication must have at least one entry
• Aidex is a robot-oriented wiki layer with stricter quotas than vector indexing

Section 13

Vector & Graph Retrieval

Published Xenkeys automatically transform into two complementary data representations, enabling hybrid AI retrieval.

Vector Index (Qdrant)

• Text source: fact + meaning + context
• Converted to high-dimensional embeddings
• Enables semantic similarity search
• Payload filters: status, geo, tags, emotions, time
• Idempotency: (id, version) key

Knowledge Graph (Neo4j)

• Nodes: Xenkey, Organization, Object, Tag, Emotion
• Edges: OWNS, DESCRIBED_BY, TAGS, EXPRESSES
• Reveals relationships and structure
• Idempotent MERGE on natural keys
• Enables graph traversal queries

Hybrid retrieval combines vector similarity with structural graph filters, enabling grounded, explainable AI responses. The indexing pipeline is asynchronous with retries and dead-letter queues.

Section 14

Invariants

✓ anchors must be present and non-empty
✓ If both age_min and age_max are present: age_max >= age_min
✓ If geo is present, must be [longitude, latitude]
✓ geo_scope=country requires country
✓ geo_scope=region requires country + region (or city)
✓ geo_scope=point requires geo
✓ aidex in publication implies vector in publication
✓ is_published=true requires non-empty publication[]

Section 15

Example Payloads

Draft Xenkey (minimal)

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
}

Published Xenkey (with geo + vector indexing)

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
}

This specification is the canonical reference for Xenkey spec=1.0.

Canonical JSON Schema: xenkey_schema_v1_0.json