Lo que se espera que haga un producer de OSIRIS JSON
Los producers de OSIRIS JSON son el punto donde el estandar se vuelve real.
Las directrices para producers y la documentacion del SDK para producers lo dejan explicito. Un producer no es solo un parser que casualmente emite JSON. Es el limite donde inventarios propietarios se traducen a un snapshot de OSIRIS determinista, portable y seguro en el que otras herramientas puedan confiar.
Un producer es un traductor de solo lectura
El primer punto importante en la guia para producers es lo que un producer no es.
No aprovisiona infraestructura. No modifica dispositivos. No inventa datos faltantes. No reinterpreta la especificacion. El trabajo de un producer es mas estrecho y mas estricto: descubrir lo que existe, normalizarlo a OSIRIS, eliminar datos inseguros o irrelevantes y emitir un snapshot que pueda ser validado por la toolchain canonica de OSIRIS.
Suena obvio, pero es la linea correcta. En el momento en que los producers empiezan a comportarse como planos de control, o empiezan a incrustar ideas personalizadas de lo que significa OSIRIS, la interoperabilidad se rompe.
El flujo de trabajo del producer es deliberado
La documentacion describe el ciclo de vida del producer en cuatro pasos: discovery, normalization, redaction y emission.
Esa secuencia importa porque cada etapa tiene una responsabilidad distinta:
- discovery recopila datos del vendor o de la plataforma
- normalization los mapea a estructuras estandar de OSIRIS
- redaction elimina secretos, PII y ruido inutil
- emission serializa el documento y lo valida antes de publicarlo
La guia tambien deja espacio para la realidad. Los inventarios parciales son aceptables. Los fallos individuales de discovery normalmente deberian registrarse y omitirse en lugar de hacer fallar toda la exportacion. Pero esa flexibilidad se detiene en el limite de seguridad: si se detectan secretos, se espera que el producer falle de forma segura.
El determinismo es una funcionalidad, no un acabado
Uno de los temas mas fuertes en ambos documentos es el determinismo.
Se espera que los ID de recursos, conexiones y grupos sean estables entre ejecuciones. La documentacion para producers insiste mucho en evitar aleatoriedad, ordenamientos inestables y nombres ad hoc. La razon es directa: si el mismo entorno produce una salida distinta cada vez, los diff, la correlacion y la automatizacion aguas abajo dejan de ser confiables.
El SDK refuerza esto con ayudas concretas:
- generacion determinista de ID a partir de claves canonicas
- manejo de colisiones en dos fases mediante un
IDRegistry - un
DocumentBuilderque gestiona$schema,version, los metadatos del generator y una salida topologica ordenada - helpers de prueba que comprueban el determinismo byte a byte y la consistencia de los golden files
Esta es una de las señales mas claras de que OSIRIS se esta diseñando para tooling de larga duracion, no para exportaciones puntuales.
La seguridad es responsabilidad del producer
Las directrices para producers son igual de firmes respecto a la redaccion.
Los documentos OSIRIS no deben contener credenciales, tokens, claves privadas ni cadenas de conexion con secretos incrustados. Se espera que los producers analicen patrones comunes antes de la emision, descompongan los valores inseguros en lugar de copiarlos completos y elijan un modo de fallo explicito.
El valor predeterminado recomendado es fail-closed. Existe un modo log-and-redact de activacion explicita, pero incluso ahi las reglas siguen siendo estrictas: no registrar nunca el valor secreto en si, marcar siempre el documento como redactado y no permitir nunca que la redaccion ocurra en silencio.
Esa es la postura correcta. Los producers estan mas cerca que nadie de los sistemas fuente en bruto, y eso los convierte en el lugar mas peligroso para actuar con descuido.
El SDK esta ahi para eliminar la deriva
El SDK de producers en Go no se presenta como infraestructura magica. Se presenta como una forma de detener la deriva de los producers.
Estandariza el contrato Collect(ctx), proporciona contexto de ejecucion compartido, factorias de recursos y relaciones, helpers de normalizacion, builders deterministas y un harness de pruebas. Igual de importante, se niega a convertirse en un segundo validador. El SDK no es propietario de los diagnosticos V-* y no importa @osirisjson/core como biblioteca. Los producers validan la salida llamando a la CLI canonica como paso externo.
Esa separacion es arquitectonicamente solida. Mantiene la logica de mapeo en los producers y la logica de validacion en el motor compartido de OSIRIS.
La confianza viene de las pruebas
El mensaje final de la documentacion para producers es que la salida de un producer debe ser reproducible y revisable.
Los golden files se tratan como la principal defensa contra regresiones. El flujo de trabajo esperado es simple: simular la entrada del vendor, generar el documento OSIRIS, compararlo con el golden file y despues validar ese artefacto con la CLI canonica bajo el perfil strict. El harness de pruebas del SDK añade helpers para ese flujo y para reejecuciones deterministas con relojes y fixtures fijos.
Esto importa porque la calidad de un producer no consiste solo en si la exportacion “funciona una vez”. Consiste en si la misma entrada sigue produciendo una salida confiable a medida que evoluciona el ecosistema.
Leer la documentacion de producers
La guia para producers esta disponible en la seccion de arquitectura de la documentacion: