Extensiones conocidas de Ossie

Cada entrada de custom_extensions[] de Ossie lleva un vendor_name + un payload JSON data de forma libre. Saiku reserva el slot vendor_name: SAIKU para un pequeño vocabulario tipado que impulsa sobrescrituras de visualización, visibilidad basada en roles, y redacción graduada de PII — todo desde un único blob escrito por admin en el campo / métrica / dataset.

Se entrega en saiku v4.7 como saiku#1409.

Paralelo a las anotaciones semánticas de Mondrian

Los schemas Mondrian usan bloques <Annotation name="saiku.semantic.*"> para la misma idea — vea Anotaciones semánticas de Saiku. Ossie usa custom_extensions[] según la especificación OSI. Misma intención, distinto formato de archivo.

Los tres conocidos

saiku.display caption / format / unit / hidden — sobrescribe cómo el schema de IA expone un campo o métrica. Hidden lo elimina por completo de las vistas orientadas a la IA.

saiku.roles listas de roles allow / deny que controlan qué campos y métricas puede ver un usuario. Parseado en v4.7; la aplicación completa aterriza con el trabajo de RLS de Ossie.

saiku.pii PII graduado — { level: redact | mask | hash }. Compatible hacia atrás con el booleano heredado 'pii: true'.

Formato de archivo

Los tres cabalgan bajo una única entrada de extensión vendor_name: SAIKU. Múltiples claves pueden coexistir en un blob:

pharma.ossie.yaml

datasets:
- name: fact_pharma
  source: FACT_PHARMA
  fields:
  - name: NETREVENUE
    expression:
      dialects: [{ dialect: ANSI_SQL, expression: NETREVENUE }]
    custom_extensions:
    - vendor_name: SAIKU
      data: |
        {
          "display": {
            "caption": "Net Revenue",
            "format": "$#,##0.00",
            "unit": "USD"
          },
          "roles": {
            "allow": ["ROLE_SALES", "ROLE_ANALYST"]
          },
          "pii": {
            "level": "redact"
          }
        }

Cada clave es independientemente opcional. Un blob con solo pii definido se comporta exactamente como el blob heredado de solo-PII; los otros consumidores no ven nada y no hacen nada.

saiku.display — sobrescrituras de presentación

custom_extensions:
- vendor_name: SAIKU
  data: |
    {
      "display": {
        "caption": "Net Revenue",
        "format": "$#,##0.00",
        "unit": "USD",
        "hidden": false
      }
    }

Clave	Tipo	Efecto
caption	string	Sobrescribe el label del campo / el displayName de la métrica en la respuesta del schema de IA. Gana sobre los renombrados de <datasource>.generated.json.
format	string	Patrón de formato de número (sintaxis DecimalFormat) que el workbench aplica al renderizar valores.
unit	string	Pista de unidad de forma libre ("USD", "hours", "%"). Se superpone al campo unit del schema.
hidden	boolean	true elimina el campo / métrica del schema de IA por completo.

Hidden vs PII

Hidden significa 'la IA no puede ver que esto existe'

hidden: true elimina el campo de las respuestas de /ai/ossie/schema/…. La IA nunca aprende que el campo existe, así que no puede consultarlo, mencionarlo, ni inventar alternativas a partir de su nombre.

PII (saiku.pii) es diferente: la IA aún puede ver que el campo existe, y puede agrupar / filtrar por él. Los valores en las respuestas de consulta se redactan (null), enmascaran (***), o hashean dependiendo del nivel — la forma estructural sobrevive.

Use hidden para campos de contabilidad administrativa (IDs internos, timestamps técnicos) que la IA no debería intentar consultar. Use pii para columnas que contienen valores sensibles pero cuya presencia es esperada.

saiku.roles — visibilidad basada en roles

custom_extensions:
- vendor_name: SAIKU
  data: |
    {
      "roles": {
        "allow": ["ROLE_SALES", "ROLE_ANALYST"],
        "deny": ["ROLE_EMBED_GUEST"]
      }
    }

Clave	Tipo	Efecto
allow	string[]	Vacío / ausente = permite a todos los llamadores. No vacío = el llamador debe tener al menos un rol coincidente.
deny	string[]	Sobrescribe a allow. Un llamador con cualquier rol denegado pierde el acceso.

Parseado hoy, aplicado con RLS de Ossie

saiku v4.7 parsea la anotación y la expone en el DTO proyectado. La aplicación completa en tiempo de ejecución — filtrar la respuesta del schema de IA y los resultados de consulta contra las autoridades de Spring Security del llamador — aterriza con el trabajo de RLS de Ossie.

Escriba las anotaciones hoy para que estén en su sitio cuando RLS se entregue; un consumidor futuro las leerá sin ningún cambio de schema.

Las cadenas de rol coinciden con los nombres de autoridad de Spring Security (ROLE_ADMIN, ROLE_SALES, etc.). Saiku no dicta una convención de nombres más allá de eso — elija nombres que coincidan con el proveedor de identidad de su operador.

saiku.pii — PII graduado

custom_extensions:
- vendor_name: SAIKU
  data: '{"pii":{"level":"hash"}}'

Extiende el booleano heredado "pii": true a una forma graduada. Tres niveles:

Nivel	Comportamiento en el cable	Use cuando …
redact	El valor es null. Igual que el booleano heredado "pii": true.	Cualquier cosa sensible que no debe salir del servidor.
mask	El valor se reemplaza con un token fijo (p. ej. "***") preservando la forma de fila.	La celda debe estar visiblemente presente pero oscurecida.
hash	El valor es un prefijo hex de hash con clave determinista (preserva la unibilidad).	Los joins aguas abajo necesitan un valor estable; el original es secreto.

Compat hacia atrás: "pii": true y "pii": {"level": "redact"} son equivalentes — la forma heredada mantiene su significado exacto.

Nota

saiku v4.7 expone piiLevel en el DTO proyectado. El escáner de PII existente todavía se dispara ante cualquier forma truthy, redactando valores. La redacción completa consciente del nivel (mask + hash) aterriza en un seguimiento.

Reglas de extensibilidad

Fijadas en v4.7 como contrato estable:

• Las claves desconocidas dentro del blob SAIKU hacen round-trip intactas. Un conocido futuro puede entregarse en un exportador más nuevo sin ninguna release coordinada — los consumidores más antiguos ignoran la clave en lugar de dar error.
• La primera entrada SAIKU gana. Si un YAML declara múltiples entradas vendor_name: SAIKU en el mismo objeto, la primera es autoritativa y el resto se ignoran. La fusión entre entradas crearía ambigüedad de orden.
• Los proveedores no-SAIKU hacen round-trip sin cambios. vendor_name: DBT, vendor_name: PREFECT, y el blob de cualquier otro integrador fluye a través del array customExtensions[] del schema de IA tal como se escribió.

Convención de espacio de nombres

vendor_name: SAIKU está reservado para los conocidos escritos por Saiku. Los integradores de terceros DEBERÍAN usar sus propios nombres de proveedor para que los consumidores aguas abajo puedan distinguir las fuentes sin nomenclatura coordinada.

Dónde aflora

Las superposiciones fluyen a dos sitios hoy:

• Navegador de schema del workbench — lee el DTO directamente, así que el caption / format / unit de visualización se renderizan en el árbol y el inspector.
• Schema Ossie de IA (GET /ai/ossie/schema/…) — los campos y métricas ocultos desaparecen; el caption + unit de visualización se superponen a los labels que el LLM ve.

A dónde ir después

Adaptador SQL de Ossie Cómo se consulta el modelo semántico. Las extensiones viajan con el schema — un campo oculto está oculto también de las vistas expuestas del adaptador SQL.

Anotaciones semánticas de Mondrian El equivalente MDX / XML de estas anotaciones. Misma intención, distinto formato de archivo.

Exportar a Apache Ossie Cómo generar el YAML Ossie a partir de un schema Mondrian existente. Las extensiones conocidas hacen round-trip a través del exportador.