Proposal: Promote Behavior Layer to semantic_model.behavior (Actions/Rules/Effects)

[zljie]

Proposal: Promote Behavior Layer to semantic_model.behavior (Actions / Rules / Effects)

Summary

This proposal introduces an optional, vendor-agnostic first-class semantic_model.behavior block to OSI Core, enabling deterministic action planning and attribution (what changed/why).

Key additions:

• semantic_model.behavior (preferred placement)
• actions (preferred) with backward-compatible alias action_types
• effects for machine-readable impact annotations on datasets/fields/metrics/relationships

Motivation

OSI already supports semantic structure (datasets/relationships/metrics), but many agent-driven use cases require behavioral semantics:

• Deterministic action planning: validate that an action plan is executable and consistent with constraints.
• Attribution: explain “what changed/why” for state fields and master data growth.
• Impact analysis: identify which actions can affect a dataset or field (e.g., state transitions).

The current approach embeds behavior as vendor JSON under custom_extensions, which makes it harder for generic tools to discover and validate behavior in a standard way.

Non-goals

• This proposal does not prescribe how actions are executed (SQL vs API vs workflow).
• This proposal does not replace custom_extensions or remove legacy behavior embeddings.

Design

1) First-class placement

Add optional semantic_model[].behavior:

• namespace (string)
• behavior_layer_version (string)
• actions (array of actions) OR action_types (legacy alias)
• rules (array)
• metadata (optional)

2) Backwards compatibility

• Legacy embedded behavior under custom_extensions remains valid.
• New tools SHOULD prefer semantic_model.behavior when present.

3) Effects (impact annotations)

Add optional effects[] to actions.

Minimal fields:

• entity: dataset/field/metric/relationship
• mode: read/write/derive
• selectors: dataset + field_names (or other selectors)
• optional: impact_type, transition, set_value, confidence, notes

Example (SAP P2P)

See: examples/p2p_behavior_effects_minimal.yaml

Compatibility & Versioning

• Additive change: behavior is optional.
• Proposed bump: version: 0.1.2 to reflect schema extension.

Questions for maintainers

1. Is the semantic_model.behavior placement acceptable as a first-class block?
2. Should actions be the preferred field name with action_types as legacy alias?
3. Is the proposed minimal effects structure sufficient, or should it be further constrained?

[jochenchrist]

Can you show some examples in BI tools that use these kinds of behavior/actions in semantic models?

I know these from ontologies, but not much for semantic models.

[zljie]

Can you show some examples in BI tools that use these kinds of behavior/actions in semantic models?

I know these from ontologies, but not much for semantic models.

Thanks for the question — there are precedents in BI/metrics tooling where parts of “behavior” (actions, constraints, and system effects) live close to the semantic model, although different vendors place them at different layers.

1) Existing BI / semantic-model precedents (quick pointers)

• Looker (LookML): semantic layer can encode interactive “behaviors”
  • Actions: drill_fields, link / html (click → drill / navigate)
  • Rules: access filters / user attributes (RLS), centralized business logic in LookML
  • Effects: PDTs + caching policies (materialization and refresh behavior)
• Power BI / Fabric Semantic Model (Tabular): strong “rules + effects” at model layer
  • Rules: DAX measures (metric definitions), RLS roles
  • Effects: aggregations, incremental refresh (model-level performance/refresh behavior)
  • (UI-style actions are often on the report layer, but the model still governs what is valid and what changes.)
• dbt Semantic Layer / MetricFlow / Cube (metrics layers): strong “rules + effects”
  • Rules: metric definitions, constraints/tests (what is allowed / expected)
  • Effects: pre-aggregations / rollups / query rewrites (performance behavior)

2) Why OSI needs first-class behavior (restaurant dashboard example)

Consider a restaurant operations dashboard with a metric “worst-selling dish”.

Without a behavior layer, the semantic model can describe what is true (dish X is worst-selling; by segment/time/channel), but it cannot reliably answer what we can do about it, nor validate or attribute proposed interventions.

With semantic_model.behavior, the model becomes a discoverable contract for:

• Actions (the action space): what interventions exist and what parameters they take.
• Rules (governance/constraints): what must hold (permissions, margin guardrails, feasibility constraints).
• Effects (impact annotations): what entities/metrics are read/written/derived, enabling blast-radius analysis and attribution (“what changed/why”).

In this example we can expose two alternative, valid plans for the same diagnostic insight (“worst-selling dish”), while ensuring constraints are not violated and the impact scope is explicit:

1. Discount promotion for the dish (subject to min-margin and max-discount constraints)
2. Reallocate near-expiry ingredients from the worst-seller to higher-demand dishes (subject to feasibility and availability constraints)

Both options are machine-discoverable, validatable, and attributable because:

• the planner enumerates candidate actions from behavior.actions,
• validates parameters against behavior.rules,
• and reports impact scope from each action’s effects (datasets/fields/metrics impacted).

I’ve attached a small, vendor-agnostic YAML snippet that demonstrates this structure:

• OSI_PR_materials/restaurant_ops_behavior_example.en.yaml

3) Connection back to OSI proposal

This is exactly why promoting behavior to a first-class semantic_model.behavior block is valuable:

• deterministic planning (executable + constraint-checked),
• attribution (“what changed / why” via explicit writes),
• and impact analysis (blast radius via effects), all in a standard place rather than vendor JSON under custom_extensions.

[zljie]

version: 0.1.2

semantic_model:
  name: restaurant_ops
  description: >
    Restaurant operations semantic model. This example demonstrates why a first-class
    semantic_model.behavior block (Actions / Rules / Effects) enables AI planning that is
    discoverable, validatable, explainable, and attributable.

  datasets:
    - name: orders
      description: "Order line items: dish_id, qty, net_sales, timestamp, channel, etc."
    - name: menu_items
      description: "Menu items (dishes): dish_id, base_price, food_cost, category, etc."
    - name: promotions
      description: "Promotions applied to dishes over time."
    - name: inventory
      description: "Ingredient inventory: ingredient_id, on_hand_qty, expiry_date, etc."
    - name: inventory_movements
      description: "Inventory transfers / allocations / movements (auditable)."

  behavior:
    namespace: restaurant.ops
    behavior_layer_version: "0.1"

    # ------------------------
    # Actions: what can be done
    # ------------------------
    actions:
      - id: discount_promotion
        title: Discount the worst-selling dish
        description: Create a time-bounded discount promotion for a specific dish.
        params:
          - name: dish_id
            type: string
          - name: discount_pct
            type: number
          - name: start_at
            type: datetime
          - name: end_at
            type: datetime
          - name: channel
            type: string
        effects:
          # write: used for attribution & auditability
          - entity: dataset
            mode: write
            selectors:
              dataset: promotions
            impact_type: create_record
            notes: "Creates a promotion record (who/what/when can be audited)."

          # read: inputs required for validation & planning
          - entity: dataset
            mode: read
            selectors:
              dataset: menu_items
              field_names: [dish_id, base_price, food_cost]
            notes: "Used to validate margin guardrails and compute effective price."

          # derive: blast radius / expected metric changes
          - entity: metric
            mode: derive
            selectors:
              dataset: orders
              field_names: [units_sold, net_sales, gross_margin]
            impact_type: kpi_shift
            confidence: 0.6
            notes: "Expected to shift sales & margin metrics for the dish/time window."

      - id: reallocate_ingredients
        title: Reallocate ingredients from the worst-selling dish to other dishes
        description: >
          Move usable ingredients to higher-demand dishes to reduce waste and improve
          overall profit. (Execution could be ERP/inventory workflow, not prescribed here.)
        params:
          - name: from_dish_id
            type: string
          - name: to_dish_id
            type: string
          - name: ingredient_id
            type: string
          - name: qty
            type: number
          - name: effective_at
            type: datetime
        effects:
          - entity: dataset
            mode: write
            selectors:
              dataset: inventory_movements
            impact_type: create_record
            notes: "Creates inventory movement / allocation plan rows (auditable)."

          - entity: dataset
            mode: read
            selectors:
              dataset: inventory
              field_names: [ingredient_id, on_hand_qty, expiry_date]
            notes: "Used to ensure feasibility and prioritize near-expiry stock."

          - entity: metric
            mode: derive
            selectors:
              dataset: inventory
              field_names: [food_waste_cost]
            impact_type: reduction
            confidence: 0.7
            notes: "Expected to reduce waste when reallocating near-expiry ingredients."

          - entity: metric
            mode: derive
            selectors:
              dataset: orders
              field_names: [units_sold, net_sales, gross_margin]
            impact_type: kpi_shift
            confidence: 0.5
            notes: "May shift sales indirectly through availability/menu mix changes."

    # ------------------------
    # Rules: constraints & governance
    # (structure is intentionally minimal and vendor-agnostic)
    # ------------------------
    rules:
      - id: rls_manager_only
        title: Only managers can execute actions
        applies_to:
          actions: [discount_promotion, reallocate_ingredients]
        constraint:
          type: role_allowlist
          roles: [manager, ops_lead]
        severity: error

      - id: discount_margin_guardrail
        title: Discount must not violate minimum margin
        applies_to:
          actions: [discount_promotion]
        constraint:
          type: expression
          language: pseudo
          expr: >
            price_after_discount(dish_id, discount_pct) >= food_cost(dish_id) * (1 + min_margin_pct)
        severity: error
        notes: "Prevents AI from proposing promotions that break profitability constraints."

      - id: discount_max_pct
        title: Discount percentage upper bound
        applies_to:
          actions: [discount_promotion]
        constraint:
          type: range
          field: discount_pct
          min: 0
          max: 0.30
        severity: error

      - id: reallocate_only_near_expiry
        title: Only reallocate ingredients near expiry (reduce waste)
        applies_to:
          actions: [reallocate_ingredients]
        constraint:
          type: expression
          language: pseudo
          expr: >
            days_until_expiry(ingredient_id) <= 3 AND on_hand_qty(ingredient_id) >= qty
        severity: error

      - id: forbid_negative_availability
        title: Reallocation cannot make target dish unavailable
        applies_to:
          actions: [reallocate_ingredients]
        constraint:
          type: expression
          language: pseudo
          expr: >
            projected_availability(to_dish_id, ingredient_id, qty, effective_at) >= 0
        severity: error

    metadata:
      intent: >
        Enable AI planners to propose multiple interventions for "worst-selling dish"
        with deterministic validation (rules) and explicit impact enumeration (effects).
      planner_contract:
        steps:
          - "Identify worst-selling dish via semantic metrics"
          - "Enumerate candidate actions from behavior.actions"
          - "Validate action parameters against behavior.rules"
          - "For each valid plan, list impacted entities via action.effects (blast radius)"
          - "Return at least two valid alternative plans when available (discount vs reallocation)"

[zljie]

Can you show some examples in BI tools that use these kinds of behavior/actions in semantic models?

I know these from ontologies, but not much for semantic models.

My take is: ontologies / semantic models are already great at describing a domain — they answer “what we have” and “what is true” (“what” / “what is”).
What I want to unlock next is using semantics to answer “what can we do” and “what will happen if we do it”.
A first-class behavior layer (actions + rules + effects) gives AI a clear action space, hard constraints, and an explicit blast radius, so recommendations become validatable, explainable, and attributable — not just ad‑hoc suggestions.
In short: it’s not replacing ontology semantics, it’s extending it from descriptive semantics to actionable/prescriptive semantics.

My north star is: for a given data domain, we should have one ontology-grade semantic model as the SSOT — just like SSOT in the data era, but for the ontology era.