Extensões well-known do Ossie

Toda entrada custom_extensions[] do Ossie carrega um vendor_name + um payload JSON data livre. O Saiku reserva o slot vendor_name: SAIKU para um pequeno vocabulário tipado que dirige sobrescritas de exibição, visibilidade baseada em role e redação graduada de PII — tudo a partir de um único blob autorado por admin no field / metric / dataset.

Distribuído no saiku v4.7 como saiku#1409.

Paralelo às anotações semânticas do Mondrian

Schemas Mondrian usam blocos <Annotation name="saiku.semantic.*"> para a mesma ideia — veja Anotações semânticas do Saiku. O Ossie usa custom_extensions[] conforme a spec OSI. Mesma intenção, formato de arquivo diferente.

Os três well-knowns

saiku.display caption / format / unit / hidden — sobrescreve como o schema AI expõe um field ou metric. Hidden o remove inteiramente das views voltadas à AI.

saiku.roles listas de role allow / deny que controlam quais fields e metrics um usuário pode ver. Parseado em v4.7; enforcement completo chega com o trabalho de RLS Ossie.

saiku.pii PII graduado — { level: redact | mask | hash }. Compatível com o booleano legado 'pii: true'.

Formato de arquivo

Todos os três viajam sob uma única entrada de extensão vendor_name: SAIKU. Múltiplas chaves podem coexistir em um 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 chave é independentemente opcional. Um blob com apenas pii definido se comporta exatamente como o blob legado só-PII; os outros consumidores não veem nada e não fazem nada.

saiku.display — sobrescritas de apresentação

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

Chave	Tipo	Efeito
caption	string	Sobrescreve o label do field / displayName do metric na resposta do schema AI. Vence sobre renomes de <datasource>.generated.json.
format	string	Padrão de number-format (sintaxe DecimalFormat) que o workbench aplica ao renderizar valores.
unit	string	Dica de unidade livre ("USD", "hours", "%"). Sobrepõe o field unit do schema.
hidden	boolean	true remove o field / metric do schema AI inteiramente.

Hidden vs PII

Hidden significa 'a AI não pode ver que isto existe'

hidden: true remove o field das respostas /ai/ossie/schema/…. A AI nunca aprende que o field existe, então não pode consultá-lo, mencioná-lo ou inventar alternativas a partir do seu nome.

PII (saiku.pii) é diferente: a AI ainda pode ver que o field existe, e pode agrupar / filtrar por ele. Valores em respostas de query são redigidos (null), mascarados (***) ou hasheados dependendo do level — o formato estrutural sobrevive.

Use hidden para fields de contabilidade de admin (IDs internos, timestamps técnicos) que a AI não deveria tentar consultar. Use pii para colunas que guardam valores sensíveis mas cuja presença é esperada.

saiku.roles — visibilidade baseada em role

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

Chave	Tipo	Efeito
allow	string[]	Vazio / ausente = permite todos os chamadores. Não-vazio = o chamador deve ter ao menos um role correspondente.
deny	string[]	Sobrescreve allow. Um chamador com qualquer role negado perde acesso.

Parseado hoje, aplicado com Ossie RLS

O saiku v4.7 parseia a anotação e a expõe no DTO projetado. O enforcement completo em runtime — filtrando a resposta do schema AI e os resultados de query contra as authorities do Spring Security do chamador — chega com o trabalho de RLS Ossie.

Autore as anotações hoje para que estejam no lugar quando o RLS chegar; um consumidor futuro vai lê-las sem nenhuma mudança de schema.

Strings de role casam com os nomes de authority do Spring Security (ROLE_ADMIN, ROLE_SALES, etc.). O Saiku não dita uma convenção de nomenclatura além disso — escolha nomes que casem com o provider de identidade do seu operador.

saiku.pii — PII graduado

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

Estende o booleano legado "pii": true para um formato graduado. Três levels:

Level	Comportamento no wire	Use quando …
redact	O valor é null. Igual ao booleano legado "pii": true.	Qualquer coisa sensível que não deve deixar o servidor.
mask	O valor é substituído por um token fixo (ex.: "***") preservando o formato da linha.	A célula deve estar visivelmente presente mas obscurecida.
hash	O valor é um prefixo hex de keyed-hash determinístico (preserva joinability).	Joins downstream precisam de um valor estável; o original é secreto.

Compat retroativa: "pii": true e "pii": {"level": "redact"} são equivalentes — a forma legada mantém seu significado exato.

Nota

O saiku v4.7 expõe piiLevel no DTO projetado. O scanner de PII existente ainda dispara em qualquer formato truthy, redigindo valores. A redação level-aware completa (mask + hash) chega em um follow-up.

Regras de extensibilidade

Fixadas em v4.7 como um contrato estável:

• Chaves desconhecidas dentro do blob SAIKU fazem round-trip intocadas. Um well-known futuro pode ser distribuído em um exportador mais novo sem nenhum release coordenado — consumidores mais antigos ignoram a chave em vez de dar erro.
• A primeira entrada SAIKU vence. Se um YAML declara múltiplas entradas vendor_name: SAIKU no mesmo objeto, a primeira é autoritativa e o resto é ignorado. Merge cross-entry criaria ambiguidade de ordenação.
• Fornecedores não-SAIKU fazem round-trip inalterados. vendor_name: DBT, vendor_name: PREFECT e o blob de qualquer outro integrador flui através do array customExtensions[] do schema AI como autorado.

Convenção de namespace

vendor_name: SAIKU é reservado para well-knowns autorados pelo Saiku. Integradores de terceiros DEVEM usar seus próprios vendor names para que consumidores downstream possam distinguir fontes sem nomenclatura coordenada.

Onde aparece

Os overlays fluem para dois lugares hoje:

• Navegador de schema do workbench — lê o DTO diretamente, então o caption / format / unit de exibição renderizam na árvore e no inspetor.
• Schema AI Ossie (GET /ai/ossie/schema/…) — fields e metrics ocultos desaparecem; caption + unit de exibição sobrepõem os labels que o LLM vê.

Para onde ir a seguir

Adaptador SQL Ossie Como o modelo semântico é consultado. Extensões viajam com o schema — um field oculto está oculto das views expostas do adaptador SQL também.

Anotações semânticas do Mondrian O equivalente MDX / XML destas anotações. Mesma intenção, formato de arquivo diferente.

Exportando para Apache Ossie Como gerar o YAML Ossie a partir de um schema Mondrian existente. Extensões well-known fazem round-trip pelo exportador.