Xenkey Specification v1.0 — Technical Documentation

Sección 1

¿Qué es un Xenkey?

Un Xenkey es una unidad atómica de significado sobre un objeto del mundo real — un negocio, producto, servicio, lugar, persona, proceso o evento. Está escrito para comprensión de IA, no para persuasión de marketing.

Cada Xenkey representa una sola idea mínima y falsable. La versión de la especificación se declara en cada documento:

encabezado del esquema

{ "spec": "1.0" }

Sección 2

Objetivos de diseño

Verdad sobre persuasión

Describe la realidad, no la promoción.

Contextualidad

Captura cuándo, dónde y para quién aplica.

Componibilidad

Muchos Xenkeys describen un objeto.

Legibilidad para IA

Estructura estricta para recuperación e indexación.

Sección 3

Identidad

Campo	Tipo	Obligatorio	Descripción
id	string	Sí	Identificador primario. Formato: xk_ + ULID
ulid	string	No	Opcional. Derivado del sufijo de id (debe coincidir si está presente)
spec	"1.0"	Sí	Versión de la especificación

Sección 4

Ciclo de vida y mutabilidad

Los Xenkeys siguen un ciclo de vida estricto que garantiza la integridad y la confianza de los datos.

Estados:

draftunpublishedpublishedarchived

Reglas de mutabilidad

•Draft — se puede editar libremente
•Published — inmutable. Los cambios requieren un nuevo Xenkey
•Si published_at está establecido, el estado no puede ser draft

Campo	Tipo	Obligatorio	Descripción
status	enum	Sí	draft \| unpublished \| published \| archived
created_at	datetime	Sí	Marca de tiempo de creación (RFC 3339)
published_at	datetime	No	Cuándo se publicó el Xenkey
updated_at	datetime	No	Interno/solo lectura, establecido por la API
etag	string	No	Interno/solo lectura, usado para control de concurrencia

Sección 5

Núcleo de significado

El corazón de cada Xenkey. Cuatro campos obligatorios que capturan una unidad estructurada de verdad.

Campo	Tipo	Obligatorio	Descripción
title	string	Sí	Identificador corto y descriptivo de la experiencia
fact	string	Sí	Afirmación factual y verificable sobre la realidad
meaning	string	Sí	Por qué este hecho importa a las personas
context	string	Sí	Cuándo, dónde y para quién aplica
constraints	string	No	Matiz en texto libre no capturado por campos estructurados

Sección 6

Alcance y anclas

Las anclas vinculan Xenkeys a entidades del mundo real. Cada Xenkey debe tener al menos una ancla. El soporte multiancla permite que un Xenkey describa la intersección de múltiples objetos.

Campo	Tipo	Obligatorio	Descripción
organization_id	string	Sí	Organización propietaria
base_id	string	Sí	Agrupación lógica (workspace/proyecto)
unit_id	string	No	Referencia opcional de entrada de datos estructurada
anchors[]	array	Sí	Arreglo de objetos ancla (mín 1)

objeto ancla

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

Tipos de ancla:

productservicepersonlocationeventprocessresource

Sección 7

Etiquetas, emociones y vibe

Campo	Tipo	Obligatorio	Descripción
tags	string[]	No	Etiquetas de clasificación (p. ej., booking_required, wifi)
emotions	string[]	No	Códigos de contexto emocional (de emotion-codes.json)
vibe	string	No	Descripción de atmósfera / estado de ánimo
seasons	string[]	No	Temporadas aplicables
time_of_day	string[]	No	Momentos del día aplicables
meal	string[]	No	Periodos de comida aplicables

Temporadas:

springsummerautumnwinterall_yearholidaynew_yearchristmasorient_new_year

Hora del día:

all_dayearly_morningmorningnoonafternooneveningnightlate_night

Comida:

breakfastbrunchlunchdinnersuppertea_timecoffee_timesnack_time

Sección 8

Demografía

Campo	Tipo	Obligatorio	Descripción
age_min	integer	No	Edad mínima recomendada
age_max	integer	No	Edad máxima recomendada (debe ser >= age_min)
gender	string	No	Género objetivo (si aplica)

Sección 9

Geografía

Los Xenkeys pueden ser globales o con alcance geográfico. El campo geo_scope determina qué campos geográficos son obligatorios.

Alcances geográficos:

globalcountryregionpoint

Campo	Tipo	Obligatorio	Descripción
geo_scope	enum	No	Nivel de precisión geográfica
country	string	No	Código de país ISO 3166-1 alpha-2
region	string	No	Región / estado / provincia
city	string	No	Nombre de la ciudad
timezone	string	No	Zona horaria IANA (p. ej., Europe/Rome)
geo	[lng, lat]	No	Coordenadas como [longitud, latitud]
availability_countries	string[]	No	Países donde está disponible (no ubicación)

Reglas de alcance: Si geo_scope=country entonces country es obligatorio. Si geo_scope=region entonces tanto country como region (o city) son obligatorios. Si geo_scope=point entonces geo es obligatorio.

Sección 10

Localización

Campo	Tipo	Obligatorio	Descripción
locale	string	Sí	Etiqueta de idioma (p. ej., en-US, ja-JP)
source_locale	string	Sí	Idioma original del contenido
translation_group	string	Sí	Agrupa traducciones. Formato: tg_ + ULID
is_source_locale	boolean	Sí	Verdadero si esta es la versión en el idioma original

Regla: Si is_source_locale = true, entonces locale debe ser igual a source_locale. Las traducciones reutilizan el mismo translation_group.

Sección 11

Integridad

Los Xenkeys publicados incluyen un hash criptográfico calculado en el momento de publicación, garantizando la integridad del contenido.

Campo	Tipo	Obligatorio	Descripción
hash_alg	"sha256"	Sí	Algoritmo de hash utilizado
hash_id	string	Sí	Identificador único de hash. Formato: hash_ + ULID
hash	string	Sí	Hash SHA-256 del payload canónico

Sección 12

Indexación y privacidad

Los Xenkeys pueden publicarse en múltiples canales. Cada canal habilita capacidades de recuperación diferentes.

Campo	Tipo	Obligatorio	Descripción
publication	string[]	No	Canales: vector, graph, aidex
is_published	boolean	No	Verdadero si se publica en al menos un canal
is_vector	boolean	No	Indexado en el store vectorial (Qdrant)
is_graph	boolean	No	Proyectado al grafo de conocimiento (Neo4j)
is_aidex	boolean	No	Publicado en Aidex, wiki orientada a robots
is_private	boolean	No	Visible solo para acceso con alcance de organización

Reglas:

• aidex requiere vector (ambos deben estar en publication)
• Siis_published=true publication debe tener al menos una entrada
• Aidex es una capa wiki orientada a robots con cuotas más estrictas que la indexación vectorial

Sección 13

Recuperación vectorial y de grafos

Los Xenkeys publicados se transforman automáticamente en dos representaciones de datos complementarias, habilitando recuperación híbrida para IA.

Índice vectorial (Qdrant)

• Fuente de texto:fact + meaning + context
• Convertido a embeddings de alta dimensionalidad
• Habilita búsqueda de similitud semántica
• Filtros de payload: estado, geo, etiquetas, emociones, tiempo
• Idempotencia: clave (id, version)

Grafo de conocimiento (Neo4j)

• Nodos: Xenkey, Organization, Object, Tag, Emotion
• Aristas: OWNS, DESCRIBED_BY, TAGS, EXPRESSES
• Revela relaciones y estructura
• MERGE idempotente sobre claves naturales
• Habilita consultas de recorrido de grafos

Recuperación híbrida combina similitud vectorial con filtros estructurales de grafo, habilitando respuestas de IA fundamentadas y explicables. El pipeline de indexación es asíncrono con reintentos y colas de mensajes muertos.

Sección 14

Invariantes

✓anchors deben estar presentes y no vacíos
✓Si ambosage_min y age_max están presentes: age_max >= age_min
✓Sigeo está presente, debe ser [longitude, latitude]
✓geo_scope=country requiere country
✓geo_scope=region requiere country + region (or city)
✓geo_scope=point requiere geo
✓aidex en publication implica vector en publication
✓is_published=true requiere publication[] no vacía

Sección 15

Payloads de ejemplo

Xenkey en borrador (mínimo)

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 publicado (con geo + indexación vectorial)

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
}

Esta especificación es la referencia canónica de Xenkey spec=1.0.

Esquema JSON canónico: xenkey_schema_v1_0.json

Especificación Xenkey v1.0