Wohlbekannte Ossie-Extensions

Jeder Ossie-custom_extensions[]-Eintrag trägt einen vendor_name + eine freiformige JSON-data-Payload. Saiku reserviert den vendor_name: SAIKU-Slot für ein kleines typisiertes Vokabular, das Anzeige-Overrides, rollenbasierte Sichtbarkeit und gestufte PII-Redaktion antreibt — alles aus einem einzigen von Admins verfassten Blob auf dem Feld / der Metrik / dem Dataset.

Ausgeliefert in saiku v4.7 als saiku#1409.

Parallel zu Mondrian-Semantik-Annotationen

Mondrian-Schemas verwenden <Annotation name="saiku.semantic.*">-Blöcke für dieselbe Idee — siehe Saiku-Semantik-Annotationen. Ossie verwendet custom_extensions[] gemäß OSI-Spezifikation. Gleiche Absicht, anderes Dateiformat.

Die drei Well-Knowns

saiku.display caption / format / unit / hidden — überschreibt, wie das AI-Schema ein Feld oder eine Metrik sichtbar macht. Hidden entfernt es vollständig aus AI-zugewandten Ansichten.

saiku.roles allow / deny Rollenlisten, die gaten, welche Felder und Metriken ein Nutzer sehen kann. Geparst in v4.7; volle Durchsetzung landet mit der Ossie-RLS-Arbeit.

saiku.pii Gestuftes PII — { level: redact | mask | hash }. Abwärtskompatibel mit dem Legacy-Boolean 'pii: true'.

Dateiformat

Alle drei reiten unter einem einzigen vendor_name: SAIKU-Extension-Eintrag. Mehrere Schlüssel können in einem Blob koexistieren:

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"
          }
        }

Jeder Schlüssel ist unabhängig optional. Ein Blob mit nur gesetztem pii verhält sich genau wie der Legacy-PII-only-Blob; die anderen Konsumenten sehen nichts und tun nichts.

saiku.display — Präsentations-Overrides

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

Schlüssel	Typ	Wirkung
caption	string	Überschreibt das Feld-Label / den Metrik-displayName in der AI-Schema-Antwort. Gewinnt über <datasource>.generated.json-Renames.
format	string	Zahlenformat-Muster (DecimalFormat-Syntax), das der Workbench beim Rendern von Werten anwendet.
unit	string	Freiformiger Einheiten-Hinweis ("USD", "hours", "%"). Schichtet auf das unit-Feld des Schemas.
hidden	boolean	true entfernt das Feld / die Metrik vollständig aus dem AI-Schema.

Hidden vs PII

Hidden bedeutet 'die AI kann nicht sehen, dass dies existiert'

hidden: true entfernt das Feld aus /ai/ossie/schema/…-Antworten. Die AI erfährt nie, dass das Feld existiert, kann es also nicht abfragen, erwähnen oder Alternativen aus seinem Namen erfinden.

PII (saiku.pii) ist anders: Die AI kann weiterhin sehen, dass das Feld existiert, und kann danach gruppieren / filtern. Werte in Abfrageantworten werden abhängig vom Level redigiert (null), maskiert (***) oder gehasht — die strukturelle Form überlebt.

Verwenden Sie hidden für Admin-Buchhaltungsfelder (interne IDs, technische Timestamps), die die AI nicht abzufragen versuchen sollte. Verwenden Sie pii für Spalten, die sensible Werte halten, deren Präsenz aber erwartet wird.

saiku.roles — rollenbasierte Sichtbarkeit

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

Schlüssel	Typ	Wirkung
allow	string[]	Leer / fehlend = alle Aufrufer erlauben. Nicht-leer = Aufrufer muss mindestens eine passende Rolle halten.
deny	string[]	Überschreibt allow. Ein Aufrufer mit irgendeiner verweigerten Rolle verliert Zugriff.

Heute geparst, durchgesetzt mit Ossie-RLS

saiku v4.7 parst die Annotation und legt sie auf dem projizierten DTO offen. Volle Laufzeit-Durchsetzung — Filtern der AI-Schema-Antwort und der Abfrageergebnisse gegen die Spring-Security-Authorities des Aufrufers — landet mit der Ossie-RLS-Arbeit.

Verfassen Sie die Annotationen heute, sodass sie an Ort und Stelle sind, wenn RLS ausgeliefert wird; ein zukünftiger Konsument wird sie ohne jegliche Schema-Änderung lesen.

Rollen-Strings entsprechen den Authority-Namen von Spring Security (ROLE_ADMIN, ROLE_SALES, etc.). Saiku diktiert darüber hinaus keine Namenskonvention — wählen Sie Namen, die zum Identity-Provider Ihres Operators passen.

saiku.pii — gestuftes PII

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

Erweitert das Legacy-"pii": true-Boolean in eine gestufte Form. Drei Level:

Level	Wire-Verhalten	Verwenden, wenn …
redact	Wert ist null. Gleich wie das Legacy-"pii": true-Boolean.	Alles Sensible, das den Server nicht verlassen darf.
mask	Wert wird durch ein festes Token ersetzt (z. B. "***"), Row-Shape bleibt.	Zelle muss sichtbar präsent, aber verschleiert sein.
hash	Wert ist ein deterministisches keyed-Hash-Hex-Präfix (bewahrt Joinbarkeit).	Nachgelagerte Joins brauchen einen stabilen Wert; das Original ist geheim.

Abwärtskompatibilität: "pii": true und "pii": {"level": "redact"} sind äquivalent — die Legacy-Form behält ihre exakte Bedeutung.

Hinweis

saiku v4.7 legt piiLevel auf dem projizierten DTO offen. Der bestehende PII-Scanner feuert weiterhin auf jede truthy Form und redigiert Werte. Volle level-bewusste Redaktion (mask + hash) landet in einem Follow-up.

Erweiterbarkeitsregeln

In v4.7 als stabiler Vertrag festgelegt:

• Unbekannte Schlüssel innerhalb des SAIKU-Blobs durchlaufen den Round-Trip unangetastet. Ein zukünftiger Well-Known kann in einem neueren Exporter ausgeliefert werden, ohne koordinierten Release — ältere Konsumenten ignorieren den Schlüssel, statt zu erroren.
• Der erste SAIKU-Eintrag gewinnt. Wenn ein YAML mehrere vendor_name: SAIKU-Einträge auf demselben Objekt deklariert, ist der erste maßgeblich und der Rest wird ignoriert. Cross-Entry-Merging würde Ordnungsmehrdeutigkeit erzeugen.
• Nicht-SAIKU-Vendoren durchlaufen den Round-Trip unverändert. vendor_name: DBT, vendor_name: PREFECT und der Blob jedes anderen Integrators fließen wie verfasst durch das AI-Schema-customExtensions[]-Array.

Namespace-Konvention

vendor_name: SAIKU ist für Saiku-verfasste Well-Knowns reserviert. Drittanbieter-Integratoren SOLLTEN ihre eigenen Vendor-Namen verwenden, sodass nachgelagerte Konsumenten Quellen ohne koordinierte Benennung unterscheiden können.

Wo es sichtbar wird

Die Overlays fließen heute an zwei Stellen:

• Workbench-Schema-Browser — liest das DTO direkt, sodass die Anzeige-Caption / -Format / -Unit im Baum und Inspector rendern.
• AI-Ossie-Schema (GET /ai/ossie/schema/…) — versteckte Felder und Metriken verschwinden; Anzeige-Caption + -Unit überlagern die Labels, die das LLM sieht.

Wohin als Nächstes

Ossie-SQL-Adapter Wie das Semantikmodell abgefragt wird. Extensions reisen mit dem Schema — ein verstecktes Feld ist auch vor den freigelegten Views des SQL-Adapters versteckt.

Mondrian-Semantik-Annotationen Das MDX- / XML-Äquivalent dieser Annotationen. Gleiche Absicht, anderes Dateiformat.

Export nach Apache Ossie Wie das Ossie-YAML aus einem bestehenden Mondrian-Schema generiert wird. Wohlbekannte Extensions durchlaufen den Exporter im Round-Trip.