Well-known Ossie extensions

Every Ossie custom_extensions[] entry carries a vendor_name + a free-form JSON data payload. Saiku reserves the vendor_name: SAIKU slot for a small typed vocabulary that drives display overrides, role-based visibility, and graded PII redaction — all from a single admin-authored blob on the field / metric / dataset.

Ships in saiku v4.7 as saiku#1409.

Parallel to Mondrian semantic annotations

Mondrian schemas use <Annotation name="saiku.semantic.*"> blocks for the same idea — see Saiku semantic annotations. Ossie uses custom_extensions[] per the OSI spec. Same intent, different file format.

The three well-knowns

saiku.display caption / format / unit / hidden — overrides how the AI schema surfaces a field or metric. Hidden strips it from AI-facing views entirely.

saiku.roles allow / deny role lists that gate which fields and metrics a user can see. Parsed in v4.7; full enforcement lands with the Ossie RLS work.

saiku.pii Graded PII — { level: redact | mask | hash }. Backwards compatible with the legacy 'pii: true' boolean.

File format

All three ride under a single vendor_name: SAIKU extension entry. Multiple keys can coexist in one 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"
          }
        }

Each key is independently optional. A blob with only pii set behaves exactly like the legacy PII-only blob; the other consumers see nothing and do nothing.

saiku.display — presentation overrides

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

Key	Type	Effect
caption	string	Overrides the field label / metric displayName in the AI schema response. Wins over <datasource>.generated.json renames.
format	string	Number-format pattern (DecimalFormat syntax) the workbench applies when rendering values.
unit	string	Free-form unit hint ("USD", "hours", "%"). Layers onto the schema’s unit field.
hidden	boolean	true strips the field / metric from the AI schema entirely.

Hidden vs PII

Hidden means 'the AI can't see this exists'

hidden: true removes the field from /ai/ossie/schema/… responses. The AI never learns the field exists, so it can’t query it, mention it, or invent alternatives from its name.

PII (saiku.pii) is different: the AI can still see the field exists, and can group / filter by it. Values in query responses are redacted (null), masked (***), or hashed depending on the level — the structural shape survives.

Use hidden for admin bookkeeping fields (internal IDs, technical timestamps) that the AI shouldn’t try to query. Use pii for columns that hold sensitive values but whose presence is expected.

saiku.roles — role-based visibility

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

Key	Type	Effect
allow	string[]	Empty / missing = allow all callers. Non-empty = caller must hold at least one matching role.
deny	string[]	Overrides allow. A caller with any denied role loses access.

Parsed today, enforced with Ossie RLS

saiku v4.7 parses the annotation and exposes it on the projected DTO. Full runtime enforcement — filtering the AI schema response and query results against the caller’s Spring Security authorities — lands with the Ossie RLS work.

Author the annotations today so they’re in place when RLS ships; a future consumer will read them without any schema change.

Role strings match Spring Security’s authority names (ROLE_ADMIN, ROLE_SALES, etc.). Saiku doesn’t dictate a naming convention beyond that — pick names that match your operator’s identity provider.

saiku.pii — graded PII

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

Extends the legacy "pii": true boolean into a graded shape. Three levels:

Level	Wire behaviour	Use when …
redact	Value is null. Same as the legacy "pii": true boolean.	Anything sensitive that must not leave the server.
mask	Value is replaced with a fixed token (e.g. "***") preserving row shape.	Cell must be visibly present but obscured.
hash	Value is a deterministic keyed-hash hex prefix (preserves joinability).	Downstream joins need a stable value; original is secret.

Backwards compat: "pii": true and "pii": {"level": "redact"} are equivalent — the legacy form keeps its exact meaning.

Note

saiku v4.7 exposes piiLevel on the projected DTO. The existing PII scanner still fires on any truthy shape, redacting values. Full level-aware redaction (mask + hash) lands in a follow-up.

Extensibility rules

Locked in v4.7 as a stable contract:

• Unknown keys within the SAIKU blob round-trip untouched. A future well-known can ship in a newer exporter without any coordinated release — older consumers ignore the key rather than error.
• First SAIKU entry wins. If a YAML declares multiple vendor_name: SAIKU entries on the same object, the first is authoritative and the rest are ignored. Cross-entry merging would create ordering ambiguity.
• Non-SAIKU vendors round-trip unchanged. vendor_name: DBT, vendor_name: PREFECT, and any other integrator’s blob flows through the AI schema customExtensions[] array as authored.

Namespace convention

vendor_name: SAIKU is reserved for Saiku-authored well-knowns. Third-party integrators SHOULD use their own vendor names so downstream consumers can distinguish sources without coordinated naming.

Where it surfaces

The overlays flow into two places today:

• Workbench schema browser — reads the DTO directly, so the display caption / format / unit render in the tree and inspector.
• AI Ossie schema (GET /ai/ossie/schema/…) — hidden fields and metrics disappear; display caption + unit overlay the labels the LLM sees.

Where to go next

Ossie SQL adapter How the semantic model is queried. Extensions travel with the schema — a hidden field is hidden from the SQL adapter's exposed views too.

Mondrian semantic annotations The MDX / XML equivalent of these annotations. Same intent, different file format.

Exporting to Apache Ossie How to generate the Ossie YAML from an existing Mondrian schema. Well-known extensions round-trip through the exporter.