Extensions Ossie bien connues

Chaque entrée custom_extensions[] d’Ossie porte un vendor_name + une charge utile JSON data en forme libre. Saiku réserve l’emplacement vendor_name: SAIKU pour un petit vocabulaire typé qui pilote les surcharges d’affichage, la visibilité basée sur les rôles et le caviardage PII gradué — le tout depuis un unique blob créé par l’administrateur sur le field / la métrique / le dataset.

Livré dans saiku v4.7 sous saiku#1409.

Parallèle aux annotations sémantiques Mondrian

Les schémas Mondrian utilisent des blocs <Annotation name="saiku.semantic.*"> pour la même idée — voir Annotations sémantiques Saiku. Ossie utilise custom_extensions[] conformément à la spec OSI. Même intention, format de fichier différent.

Les trois well-knowns

saiku.display caption / format / unit / hidden — surcharge la manière dont le schéma IA expose un field ou une métrique. Hidden le retire entièrement des vues destinées à l'IA.

saiku.roles listes de rôles allow / deny qui contrôlent quels fields et métriques un utilisateur peut voir. Parsées en v4.7 ; application complète avec le travail Ossie RLS.

saiku.pii PII gradué — { level: redact | mask | hash }. Rétrocompatible avec le booléen historique 'pii: true'.

Format de fichier

Les trois voyagent sous une unique entrée d’extension vendor_name: SAIKU. Plusieurs clés peuvent coexister dans un seul 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"
          }
        }

Chaque clé est indépendamment optionnelle. Un blob avec seulement pii défini se comporte exactement comme le blob historique PII-uniquement ; les autres consommateurs ne voient rien et ne font rien.

saiku.display — surcharges de présentation

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

Clé	Type	Effet
caption	string	Surcharge le libellé du field / le displayName de la métrique dans la réponse du schéma IA. L’emporte sur les renommages <datasource>.generated.json.
format	string	Motif de format numérique (syntaxe DecimalFormat) que le workbench applique lors du rendu des valeurs.
unit	string	Indice d’unité en forme libre ("USD", "hours", "%"). Se superpose au champ unit du schéma.
hidden	boolean	true retire entièrement le field / la métrique du schéma IA.

Hidden vs PII

Hidden signifie « l'IA ne peut pas voir que ceci existe »

hidden: true retire le field des réponses /ai/ossie/schema/…. L’IA n’apprend jamais que le field existe, donc elle ne peut pas l’interroger, le mentionner ni inventer d’alternatives à partir de son nom.

Le PII (saiku.pii) est différent : l’IA peut toujours voir que le field existe, et peut grouper / filtrer par lui. Les valeurs dans les réponses de requête sont caviardées (null), masquées (***) ou hachées selon le niveau — la forme structurelle survit.

Utilisez hidden pour les fields de comptabilité administrative (IDs internes, timestamps techniques) que l’IA ne devrait pas essayer d’interroger. Utilisez pii pour les colonnes qui contiennent des valeurs sensibles mais dont la présence est attendue.

saiku.roles — visibilité basée sur les rôles

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

Clé	Type	Effet
allow	string[]	Vide / absent = autorise tous les appelants. Non vide = l’appelant doit détenir au moins un rôle correspondant.
deny	string[]	L’emporte sur allow. Un appelant avec un rôle refusé perd l’accès.

Parsée aujourd'hui, appliquée avec Ossie RLS

saiku v4.7 parse l’annotation et l’expose sur le DTO projeté. L’application complète à l’exécution — filtrer la réponse du schéma IA et les résultats de requête par rapport aux autorités Spring Security de l’appelant — arrive avec le travail Ossie RLS.

Créez les annotations dès aujourd’hui pour qu’elles soient en place quand RLS sera livré ; un futur consommateur les lira sans aucun changement de schéma.

Les chaînes de rôle correspondent aux noms d’autorité de Spring Security (ROLE_ADMIN, ROLE_SALES, etc.). Saiku ne dicte pas de convention de nommage au-delà de cela — choisissez des noms qui correspondent au fournisseur d’identité de votre opérateur.

saiku.pii — PII gradué

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

Étend le booléen historique "pii": true en une forme graduée. Trois niveaux :

Niveau	Comportement sur le wire	À utiliser quand …
redact	La valeur est null. Identique au booléen historique "pii": true.	Tout ce qui est sensible et ne doit pas quitter le serveur.
mask	La valeur est remplacée par un jeton fixe (par ex. "***") préservant la forme de ligne.	La cellule doit être visiblement présente mais obscurcie.
hash	La valeur est un préfixe hex de hachage à clé déterministe (préserve la joignabilité).	Les joins en aval ont besoin d’une valeur stable ; l’original est secret.

Rétrocompatibilité : "pii": true et "pii": {"level": "redact"} sont équivalents — la forme historique garde son sens exact.

Note

saiku v4.7 expose piiLevel sur le DTO projeté. Le scanner PII existant se déclenche toujours sur toute forme véridique (truthy), en caviardant les valeurs. Le caviardage complet conscient du niveau (mask + hash) arrive dans un suivi.

Règles d’extensibilité

Verrouillées en v4.7 comme un contrat stable :

• Les clés inconnues au sein du blob SAIKU font un round-trip intact. Un futur well-known peut être livré dans un exporteur plus récent sans aucune release coordonnée — les consommateurs plus anciens ignorent la clé plutôt que d’échouer.
• La première entrée SAIKU l’emporte. Si un YAML déclare plusieurs entrées vendor_name: SAIKU sur le même objet, la première fait autorité et les autres sont ignorées. La fusion inter-entrées créerait une ambiguïté d’ordonnancement.
• Les fournisseurs non-SAIKU font un round-trip inchangé. vendor_name: DBT, vendor_name: PREFECT et le blob de tout autre intégrateur circule à travers le tableau customExtensions[] du schéma IA tel qu’il a été créé.

Convention d’espace de noms

vendor_name: SAIKU est réservé aux well-knowns créés par Saiku. Les intégrateurs tiers DEVRAIENT utiliser leurs propres noms de fournisseur pour que les consommateurs en aval puissent distinguer les sources sans nommage coordonné.

Où cela apparaît

Les surcouches circulent aujourd’hui vers deux endroits :

• Navigateur de schéma du workbench — lit le DTO directement, donc la caption / le format / l’unité d’affichage s’affichent dans l’arbre et l’inspecteur.
• Schéma IA Ossie (GET /ai/ossie/schema/…) — les fields et métriques cachés disparaissent ; la caption + l’unité d’affichage surchargent les libellés que le LLM voit.

Où aller ensuite

Adaptateur SQL Ossie Comment le modèle sémantique est interrogé. Les extensions voyagent avec le schéma — un field caché est aussi caché des vues exposées de l'adaptateur SQL.

Annotations sémantiques Mondrian L'équivalent MDX / XML de ces annotations. Même intention, format de fichier différent.

Export vers Apache Ossie Comment générer le YAML Ossie à partir d'un schéma Mondrian existant. Les extensions bien connues font un round-trip à travers l'exporteur.