Definiciones de negocio¶

Los documentos cuentan lo que está escrito. Las definiciones cuentan lo que tu organización ha decidido, que suele ser justo la parte que nadie escribió, o que se escribió cuatro veces de forma distinta.

Una definición es una entrada que tu equipo posee, aprueba y versiona. Una vez aprobada, rige las respuestas: preguntas qué significa un término y recibes la respuesta oficial, no el párrafo más parecido.

Los cuatro tipos¶

Tipo	Qué recoge	Ejemplo
`metric`	Una métrica de negocio y cómo se calcula	ingresos: ingreso reconocido según contrato, sin créditos promocionales
`entity`	La fuente canónica de un concepto	cliente: la tabla de cuentas de facturación es la fuente oficial; el CRM es un espejo
`rule`	Conocimiento condicional que vive en la cabeza de la gente	los deals nuevos de USCAN desde 2025 están en Affinity; los leads globales anteriores, en el CRM
`glossary`	Un término del dominio con sus alias	churn: baja efectiva al final del periodo de facturación

Las reglas son las que los equipos infravaloran. Son lo que le contarías a alguien en su primera semana: ese conocimiento condicional de «depende del año y de la región» que ningún documento enuncia y que toda respuesta correcta necesita.

Crear una¶

curl -X POST $RENBASE_API/v1/context \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"kind": "metric",
       "name": "ingresos",
       "aliases": ["ingreso neto", "ingreso reconocido"],
       "body": "Ingreso reconocido según contrato, sin créditos promocionales.",
       "code": "select sum(amount_eur) from fct_revenue",
       "scope": {"region": "EMEA", "from": "2025-01-01"},
       "approve": true}'

aliases es como lo dice la gente de verdad. Todos resuelven a la misma entrada.
code es opcional y guarda la consulta o la referencia que materializa la métrica, para las personas y los agentes que la necesiten.
scope registra en qué condiciones vale la definición: una región, un sistema, un rango de fechas.
approve: true la publica al momento. Si lo omites, la entrada espera en la cola de revisión.

Revisión y aprobación¶

Todo lo que propone una máquina llega como borrador, y los borradores no afectan a las respuestas.

# La cola de revisión
curl "$RENBASE_API/v1/context?status=draft" -H "Authorization: Bearer $ADMIN_TOKEN"

# Aprobar o rechazar
curl -X POST $RENBASE_API/v1/context/{id}/approve -H "Authorization: Bearer $ADMIN_TOKEN"
curl -X POST $RENBASE_API/v1/context/{id}/reject  -H "Authorization: Bearer $ADMIN_TOKEN"

Editar una entrada aprobada (PATCH) crea una versión nueva ya aprobada que reemplaza a la anterior. No se sobrescribe nada y el historial sigue disponible.

Renbase Studio tiene esa misma cola con interfaz de revisión, que es donde la mayoría de equipos hace esto.

Cómo llegan las definiciones a las respuestas¶

Cuando una pregunta menciona una entrada aprobada por su nombre o por un alias, esa entrada se resuelve de forma exacta y entra en la respuesta como fuente fija, por delante de cualquier búsqueda. Es una consulta directa, no una coincidencia por parecido: para «¿qué significa aquí ingresos?» necesitas la respuesta gobernada, no el párrafo más similar.

Para las preguntas que no nombran nada con precisión, las definiciones compiten igualmente junto a los documentos en la búsqueda, así que una definición bien escrita aparece por méritos propios.

Para resolver un término sin lanzar una pregunta completa —barato, y no consume créditos:

curl -G $RENBASE_API/v1/context/resolve --data-urlencode 'q=¿qué son los ingresos?' \
  -H "Authorization: Bearer $RENBASE_KEY"

Conflictos¶

Dos entradas aprobadas del mismo término con ámbitos que se solapan quedan marcadas como conflicto, y no se oculta ninguna. Una respuesta que toque ese término devuelve las dos, con su procedencia, y advierte de que no coinciden.

Es deliberado. Un sistema que elige una en silencio es un sistema que dará con aplomo la respuesta de finanzas a una pregunta de producto. Sacar el desacuerdo a la luz es lo que permite a tu equipo resolverlo.

Frescura¶

Cada entrada guarda la fecha en que se verificó por última vez contra su fuente, y esa fecha viaja en la cita. Cuando la fuente de una definición desaparece, la entrada queda marcada como caducada: sigue funcionando, pero las respuestas avisan de que puede estar desactualizada. Retirarla es una decisión humana, nunca automática.

Importar lo que ya tienes¶

Las definiciones rara vez se empiezan de cero. Si tus herramientas de datos ya documentan modelos, métricas y columnas, puedes importarlas: la extracción produce un candidato por modelo, métrica o término documentado.

curl -X POST $RENBASE_API/v1/context/import \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"candidates": [{"kind": "entity", "name": "pedidos", "body": "…", "source": {"key": "model.pedidos"}}]}'

Tres propiedades que importan en la práctica:

Las importaciones nunca aprueban. Todo llega como borrador. La herramienta propone; tu equipo decide.
Reimportar es seguro. Cada candidato lleva una clave estable y una huella del contenido: lo que no ha cambiado se reverifica en vez de duplicarse, y lo que sí crea el borrador de la versión siguiente.
dry_run enseña el plan sin escribir nada.

Los conectores con la plataforma de datos de tu organización —incluido uno que corre en tu lado y lee el esquema del warehouse sin que esas credenciales salgan de tu red— se configuran con nuestro equipo durante la puesta en marcha.

Convertir quejas en reglas¶

Cuando alguien marca una respuesta como poco útil y explica por qué, esa corrección es la mejor materia prima que tienes. La cola de refinamiento las lista, y una corrección se puede promocionar directamente a regla:

curl $RENBASE_API/v1/feedback -H "Authorization: Bearer $ADMIN_TOKEN"

curl -X POST $RENBASE_API/v1/feedback/{id}/promote \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"approve": true}'

Cada respuesta mala que alguien corrige mejora todas las siguientes, y queda registrado quién decidió qué.