Xenkey Specification v1.0 — Technical Documentation

Abschnitt 1

Was ist ein Xenkey?

Ein Xenkey ist eine atomare Bedeutungseinheit über ein Objekt der realen Welt — ein Unternehmen, Produkt, eine Dienstleistung, ein Ort, eine Person, ein Prozess oder ein Ereignis. Er ist für KI-Verständnis geschrieben, nicht für Marketing-Persuasion.

Jeder Xenkey repräsentiert eine einzige, minimale, falsifizierbare Idee. Die Spezifikationsversion wird in jedem Dokument angegeben:

Schema-Header

{ "spec": "1.0" }

Abschnitt 2

Designziele

Wahrheit statt Überzeugung

Beschreibe Realität, nicht Promotion.

Kontextualität

Erfasse, wann, wo und für wen es gilt.

Komponierbarkeit

Viele Xenkeys beschreiben ein Objekt.

KI-Lesbarkeit

Strenge Struktur für Retrieval und Indexierung.

Abschnitt 3

Identität

Feld	Typ	Erforderlich	Beschreibung
id	string	Ja	Primärer Identifier. Format: xk_ + ULID
ulid	string	Nein	Optional. Abgeleitet vom id-Suffix (muss übereinstimmen, falls vorhanden)
spec	"1.0"	Ja	Spezifikationsversion

Abschnitt 4

Lebenszyklus & Mutabilität

Xenkeys folgen einem strengen Lebenszyklus, der Datenintegrität und Vertrauen sicherstellt.

Status:

draftunpublishedpublishedarchived

Mutabilitätsregeln

•Draft — kann frei bearbeitet werden
•Published — unveränderlich. Änderungen erfordern einen neuen Xenkey
•Wenn published_at gesetzt ist, kann der Status nicht draft

Feld	Typ	Erforderlich	Beschreibung
status	enum	Ja	draft \| unpublished \| published \| archived
created_at	datetime	Ja	Erstellungszeitstempel (RFC 3339)
published_at	datetime	Nein	Wann der Xenkey veröffentlicht wurde
updated_at	datetime	Nein	Intern/Read-only, von der API gesetzt
etag	string	Nein	Intern/Read-only, für Concurrency-Control

Abschnitt 5

Bedeutungskern

Das Herz jedes Xenkey. Vier Pflichtfelder, die eine strukturierte Einheit der Wahrheit erfassen.

Feld	Typ	Erforderlich	Beschreibung
title	string	Ja	Kurzer, beschreibender Identifier für die Erfahrung
fact	string	Ja	Faktische, überprüfbare Aussage über die Realität
meaning	string	Ja	Warum dieser Fakt für Menschen wichtig ist
context	string	Ja	Wann, wo und für wen dies gilt
constraints	string	Nein	Freiform-Nuancen, die nicht durch strukturierte Felder erfasst werden

Abschnitt 6

Umfang & Anker

Anker verbinden Xenkeys mit realen Entitäten. Jeder Xenkey muss mindestens einen Anker haben. Multi-Anker-Support ermöglicht es, dass ein Xenkey die Schnittmenge mehrerer Objekte beschreibt.

Feld	Typ	Erforderlich	Beschreibung
organization_id	string	Ja	Besitzende Organisation
base_id	string	Ja	Logische Gruppierung (Workspace/Projekt)
unit_id	string	Nein	Optionale Referenz auf strukturierte Dateneinträge
anchors[]	array	Ja	Array von Anker-Objekten (mind. 1)

Anker-Objekt

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

Anker-Typen:

productservicepersonlocationeventprocessresource

Abschnitt 7

Tags, Emotionen & Vibe

Feld	Typ	Erforderlich	Beschreibung
tags	string[]	Nein	Klassifikations-Tags (z. B. booking_required, wifi)
emotions	string[]	Nein	Emotionskontext-Codes (aus emotion-codes.json)
vibe	string	Nein	Atmosphäre / Stimmung
seasons	string[]	Nein	Anwendbare Jahreszeiten
time_of_day	string[]	Nein	Anwendbare Tageszeiten
meal	string[]	Nein	Anwendbare Mahlzeiten

Jahreszeiten:

springsummerautumnwinterall_yearholidaynew_yearchristmasorient_new_year

Tageszeit:

all_dayearly_morningmorningnoonafternooneveningnightlate_night

Mahlzeit:

breakfastbrunchlunchdinnersuppertea_timecoffee_timesnack_time

Abschnitt 8

Demografie

Feld	Typ	Erforderlich	Beschreibung
age_min	integer	Nein	Empfohlenes Mindestalter
age_max	integer	Nein	Empfohlenes Höchstalter (muss >= age_min sein)
gender	string	Nein	Zielgeschlecht (falls anwendbar)

Abschnitt 9

Geografie

Xenkeys können global sein oder geospezifisch. Das Feld geo_scope bestimmt, welche geografischen Felder erforderlich sind.

Geo-Scopes:

globalcountryregionpoint

Feld	Typ	Erforderlich	Beschreibung
geo_scope	enum	Nein	Grad der geografischen Genauigkeit
country	string	Nein	ISO 3166-1 alpha-2 Ländercode
region	string	Nein	Region / Bundesland / Provinz
city	string	Nein	Stadtname
timezone	string	Nein	IANA-Zeitzone (z. B. Europe/Rome)
geo	[lng, lat]	Nein	Koordinaten als [Longitude, Latitude]
availability_countries	string[]	Nein	Länder, in denen verfügbar (nicht Standort)

Scope-Regeln: Wenn geo_scope=country dann ist country erforderlich. Wenn geo_scope=region dann sind country und region (oder city) erforderlich. Wenn geo_scope=point dann ist geo erforderlich.

Abschnitt 10

Lokalisierung

Feld	Typ	Erforderlich	Beschreibung
locale	string	Ja	Sprach-Tag (z. B. en-US, ja-JP)
source_locale	string	Ja	Originalsprache des Inhalts
translation_group	string	Ja	Gruppiert Übersetzungen. Format: tg_ + ULID
is_source_locale	boolean	Ja	True, wenn dies die Originalsprach-Version ist

Regel: Wenn is_source_locale = true, dann muss locale gleich source_locale. sein. Übersetzungen verwenden dasselbe translation_group.

Abschnitt 11

Integrität

Veröffentlichte Xenkeys enthalten einen kryptografischen Hash, der zum Zeitpunkt der Veröffentlichung berechnet wird und die Inhaltsintegrität sicherstellt.

Feld	Typ	Erforderlich	Beschreibung
hash_alg	"sha256"	Ja	Verwendeter Hash-Algorithmus
hash_id	string	Ja	Eindeutige Hash-ID. Format: hash_ + ULID
hash	string	Ja	SHA-256 Hash des kanonischen Payloads

Abschnitt 12

Indexierung & Privatsphäre

Xenkeys können in mehreren Kanälen veröffentlicht werden. Jeder Kanal ermöglicht unterschiedliche Retrieval-Fähigkeiten.

Feld	Typ	Erforderlich	Beschreibung
publication	string[]	Nein	Kanäle: vector, graph, aidex
is_published	boolean	Nein	True, wenn in mindestens einem Kanal veröffentlicht
is_vector	boolean	Nein	In Vektor-Store indexiert (Qdrant)
is_graph	boolean	Nein	In Wissensgraph projiziert (Neo4j)
is_aidex	boolean	Nein	In Aidex veröffentlicht, einer robot-orientierten Wiki-Schicht
is_private	boolean	Nein	Sichtbar nur für org-spezifischen Zugriff

Regeln:

• aidex erfordert vector (beide müssen in publication sein)
• Wennis_published=true muss publication mindestens einen Eintrag haben
• Aidex ist eine robot-orientierte Wiki-Schicht mit strengeren Quoten als die Vektor-Indexierung

Abschnitt 13

Vektor- & Graph-Retrieval

Veröffentlichte Xenkeys transformieren sich automatisch in zwei komplementäre Datenrepräsentationen und ermöglichen hybrides KI-Retrieval.

Vektorindex (Qdrant)

• Textquelle:fact + meaning + context
• In hochdimensionale Embeddings umgewandelt
• Ermöglicht semantische Ähnlichkeitssuche
• Payload-Filter: status, geo, tags, emotions, time
• Idempotenz: (id, version) Schlüssel

Wissensgraph (Neo4j)

• Knoten: Xenkey, Organization, Object, Tag, Emotion
• Kanten: OWNS, DESCRIBED_BY, TAGS, EXPRESSES
• Zeigt Beziehungen und Struktur
• Idempotentes MERGE auf natürlichen Schlüsseln
• Ermöglicht Graph-Traversal-Queries

Hybrides Retrieval kombiniert Vektorähnlichkeit mit strukturellen Graph-Filtern und ermöglicht fundierte, erklärbare KI-Antworten. Die Indexing-Pipeline ist asynchron mit Retries und Dead-Letter-Queues.

Abschnitt 14

Invarianten

✓anchors müssen vorhanden und nicht leer sein
✓Wenn sowohlage_min und age_max vorhanden sind: age_max >= age_min
✓Wenngeo vorhanden ist, muss es [longitude, latitude]
✓geo_scope=country erfordert country
✓geo_scope=region erfordert country + region (or city)
✓geo_scope=point erfordert geo
✓aidex in publication impliziert vector in publication
✓is_published=true erfordert nicht-leere publication[]

Abschnitt 15

Beispiel-Payloads

Entwurf 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
}

Veröffentlichter Xenkey (mit geo + Vektorindexierung)

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
}

Diese Spezifikation ist die kanonische Referenz für Xenkey spec=1.0.

Kanonisches JSON-Schema: xenkey_schema_v1_0.json

Xenkey Spezifikation v1.0