Referencia de la API OSL

Esta sección define los contratos públicos del motor OSL. Lo que aquí se afirma es lo que cualquier cliente puede asumir, y lo que cualquier motor conforme con OSL DEBE implementar exactamente.

Para la semántica completa de los objetos (qué primitivas existen, sus campos) ver la especificación. Aquí: cómo se invoca y qué devuelve.

Superficies

OSL v1 expone cuatro superficies separadas:

Superficie	Quién la consume	Forma
REST	Tools de BI, apps, dashboards, scripts	HTTP/JSON · Arrow IPC opcional para el bulk de /query
Tools MCP	Agentes de IA (Claude, GPT, Copilot, custom)	definiciones de tools sobre el protocolo MCP
CLI	Desarrolladores, pipelines de CI	el binario osl
Eventos OpenLineage	Marquez, DataHub, observabilidad	emisor webhook / kafka

Un solo endpoint de consumo

Todo lo que lees pasa por un único endpoint — /osl/query. La analítica estructurada, las métricas, el retrieval vectorial gobernado, los registros de entidad y la travesía de grafos son todos formas de la superficie OSL-SQL.

Los cinco endpoints ahora son uno

Los antiguos endpoints /osl/retrieve, /osl/joint/resolve y /osl/traverse han sido eliminados — cada uno es una forma de /osl/query (RETRIEVE(...), un select de registro Joint, TRAVERSE(...)). Esto es lo que hace literalmente cierto que “OSL es la única capa de consumo”.

Endpoint	Propósito
POST /osl/query	La superficie de consumo — OSL-SQL (osql), sql crudo o MetricFlow
POST /osl/sample	Previsualización de contenido gobernada — ACL + redacción server-side (no es una consulta del álgebra)
GET /osl/domain-map	El grafo de dominio unificado (Entities, métricas, candidatas)
GET /osl/schema	El manifest compilado (cacheable)
GET /osl/schema/resolve	Resolver del lexicon — término de negocio → FQN canónico
POST /osl/suggest · POST /osl/validate · POST /osl/objects	Autoría asistida (draft → validate → publish)
GET /osl/candidates	Descubrimiento — entidades candidatas (aún no adoptadas)
GET /osl/conformance	Niveles de conformidad declarados
GET /health	Health check sin autenticación

La superficie de consultas (OSL-SQL)El único endpoint y sus cinco formas.

Retrieval (RETRIEVE)Retrieval vectorial gobernado como fuente de relación.

AutenticaciónCadenas de delegación atestiguadas, scopes, rate limits.

Errores y códigos de estadoEl envelope de error y las bandas de E-codes.

Tools MCP

OSL incluye tools MCP que cualquier agente puede invocar: metric_lookup, doc_search, entity_get, schema_describe, joint_explore. Llaman a los mismos resolvers gobernados que respaldan las formas de OSL-SQL — doc_search envuelve RETRIEVE, entity_get envuelve la forma de registro Joint — así que un agente obtiene la misma aplicación que cualquier otro consumidor.

Versionado de la API

/osl/ es la raíz v1. Una v2 con cambios incompatibles viviría en /osl/v2/ mientras /osl/ sigue sirviendo el contrato v1 durante al menos dos versiones menores consecutivas. Los endpoints PUEDEN añadir campos de respuesta opcionales dentro de v1.x; los clientes DEBEN ignorar los campos no reconocidos.