Semantic Model configuration

Download JSON Schema

Example

apiVersion: leapview.dev/v1
kind: SemanticModel
metadata:
  id: semantic-model:finance
  name: finance
  displayName: CFO Finance Model
  description: Governed CFO fact constellation with conformed finance dimensions and decision-ready metrics.
  owner: Finance
  tags: [finance, governed]
spec:
  datasets:
    - name: financial_performance
      model: financial_performance
      defaultTimeDimension: finance_date
      metrics:
        - name: units_sold
          type: simple
          empty: zero
          label: Units sold
          format: decimal
          agg: sum
        - name: gross_sales
          type: simple
          empty: zero
          label: Gross sales
          unit: USD
          format: currency
          agg: sum
        - name: discounts
          type: simple
          empty: zero
          label: Discounts
          unit: USD
          format: currency
          agg: sum
        - name: net_sales
          type: simple
          empty: zero
          label: Net revenue
          unit: USD
          format: currency
          agg: sum
        - name: cogs
          type: simple
          empty: zero
          label: Cost of goods sold
          unit: USD
          format: currency
          agg: sum
        - name: gross_profit
          type: simple
          empty: zero
          label: Gross profit
          unit: USD
          format: currency
          agg: sum
        - name: budget_sales
          type: simple
          empty: zero
          label: Budget revenue
          unit: USD
          format: currency
          agg: sum
        - name: budget_gross_profit
          type: simple
          empty: zero
          label: Budget gross profit
          unit: USD
          format: currency
          agg: sum
        - name: forecast_sales
          type: simple
          empty: zero
          label: Forecast revenue
          unit: USD
          format: currency
          agg: sum
        - name: forecast_gross_profit
          type: simple
          empty: zero
          label: Forecast gross profit
          unit: USD
          format: currency
          agg: sum
        - name: ebitda
          type: simple
          empty: zero
          label: EBITDA
          unit: USD
          format: currency
          agg: sum
        - name: budget_ebitda
          type: simple
          empty: zero
          label: Budget EBITDA
          unit: USD
          format: currency
          agg: sum
        - name: forecast_ebitda
          type: simple
          empty: zero
          label: Forecast EBITDA
          unit: USD
          format: currency
          agg: sum
      dimensions:
        - name: scorecard_group
          datatype: String
        - name: record_id
          datatype: String
    - name: pnl_statement
      model: pnl_statement
      defaultTimeDimension: finance_date
      metrics:
        - name: pnl_actual
          type: simple
          empty: zero
          label: Actual
          unit: USD
          format: currency
          agg: sum
          field: actual_amount
        - name: pnl_budget
          type: simple
          empty: zero
          label: Budget
          unit: USD
          format: currency
          agg: sum
          field: budget_amount
        - name: pnl_forecast
          type: simple
          empty: zero
          label: Forecast
          unit: USD
          format: currency
          agg: sum
          field: forecast_amount
        - name: pnl_variance
          type: simple
          empty: zero
          label: F/(U)
          unit: USD
          format: currency
          agg: sum
          field: variance_amount
      dimensions:
        - name: pnl_group
          datatype: String
    - name: variance_drivers
      model: variance_drivers
      defaultTimeDimension: finance_date
      metrics:
        - name: variance_impact
          type: simple
          empty: zero
          label: EBITDA variance impact
          unit: USD
          format: currency
          agg: sum
          field: impact
    - name: cash_forecast
      model: cash_forecast
      defaultTimeDimension: week_start
      metrics:
        - name: collections
          type: simple
          empty: zero
          label: Collections
          unit: USD
          format: currency
          agg: sum
        - name: supplier_payments
          type: simple
          empty: zero
          label: Supplier payments
          unit: USD
          format: currency
          agg: sum
        - name: net_cash_flow
          type: simple
          empty: zero
          label: Net cash flow
          unit: USD
          format: currency
          agg: sum
        - name: base_collections
          type: simple
          empty: zero
          label: Base collections
          unit: USD
          format: currency
          agg: sum
        - name: base_supplier_payments
          type: simple
          empty: zero
          label: Base supplier payments
          unit: USD
          format: currency
          agg: sum
        - name: base_net_cash_flow
          type: simple
          empty: zero
          label: Base net cash flow
          unit: USD
          format: currency
          agg: sum
        - name: closing_cash
          type: simple
          empty: zero
          label: Closing cash
          unit: USD
          format: currency
          agg: sum
        - name: scenario_ending_cash
          type: simple
          empty: 'null'
          label: Ending cash
          unit: USD
          format: currency
          agg: max
        - name: scenario_headroom
          type: simple
          empty: 'null'
          label: Headroom
          unit: USD
          format: currency
          agg: max
        - name: scenario_cumulative_net_cash_flow
          type: simple
          empty: zero
          label: Net cash flow
          unit: USD
          format: currency
          agg: sum
          field: net_cash_flow
        - name: current_cash
          type: simple
          empty: 'null'
          label: Current cash
          unit: USD
          format: currency
          agg: max
        - name: base_ending_cash
          type: simple
          empty: 'null'
          label: Base ending cash
          unit: USD
          format: currency
          agg: max
        - name: base_headroom
          type: simple
          empty: 'null'
          label: Base cash headroom
          unit: USD
          format: currency
          agg: max
        - name: overdue_receivables
          type: simple
          empty: 'null'
          label: Overdue receivables
          unit: USD
          format: currency
          agg: max
        - name: dso_days
          type: simple
          empty: 'null'
          label: Days sales outstanding
          format: decimal
          agg: max
    - name: finance_dates
      model: finance_dates
    - name: finance_segments
      model: finance_segments
    - name: finance_countries
      model: finance_countries
    - name: finance_products
      model: finance_products
    - name: finance_discount_bands
      model: finance_discount_bands
    - name: pnl_lines
      model: pnl_lines
    - name: variance_driver_dimension
      model: variance_driver_dimension
    - name: cash_weeks
      model: cash_weeks
    - name: cash_scenarios
      model: cash_scenarios
  relationships:
    - name: financial_performance_date
      from: { dataset: financial_performance, entity: finance_date }
      to: { dataset: finance_dates, entity: finance_date }
    - name: pnl_statement_date
      from: { dataset: pnl_statement, entity: finance_date }
      to: { dataset: finance_dates, entity: finance_date }
    - name: variance_drivers_date
      from: { dataset: variance_drivers, entity: finance_date }
      to: { dataset: finance_dates, entity: finance_date }
    - name: financial_performance_segment
      from: { dataset: financial_performance, entity: segment }
      to: { dataset: finance_segments, entity: segment }
    - name: pnl_statement_segment
      from: { dataset: pnl_statement, entity: segment }
      to: { dataset: finance_segments, entity: segment }
    - name: variance_drivers_segment
      from: { dataset: variance_drivers, entity: segment }
      to: { dataset: finance_segments, entity: segment }
    - name: financial_performance_country
      from: { dataset: financial_performance, entity: country }
      to: { dataset: finance_countries, entity: country }
    - name: pnl_statement_country
      from: { dataset: pnl_statement, entity: country }
      to: { dataset: finance_countries, entity: country }
    - name: variance_drivers_country
      from: { dataset: variance_drivers, entity: country }
      to: { dataset: finance_countries, entity: country }
    - name: financial_performance_product
      from: { dataset: financial_performance, entity: product }
      to: { dataset: finance_products, entity: product }
    - name: pnl_statement_product
      from: { dataset: pnl_statement, entity: product }
      to: { dataset: finance_products, entity: product }
    - name: variance_drivers_product
      from: { dataset: variance_drivers, entity: product }
      to: { dataset: finance_products, entity: product }
    - name: financial_performance_discount_band
      from: { dataset: financial_performance, entity: discount_band }
      to: { dataset: finance_discount_bands, entity: discount_band }
    - name: pnl_statement_line
      from: { dataset: pnl_statement, entity: pnl_line }
      to: { dataset: pnl_lines, entity: pnl_line }
    - name: variance_drivers_driver
      from: { dataset: variance_drivers, entity: variance_driver }
      to: { dataset: variance_driver_dimension, entity: variance_driver }
    - name: cash_forecast_week
      from: { dataset: cash_forecast, entity: cash_week }
      to: { dataset: cash_weeks, entity: cash_week }
    - name: cash_forecast_scenario
      from: { dataset: cash_forecast, entity: cash_scenario }
      to: { dataset: cash_scenarios, entity: cash_scenario }
  dimensions:
    - name: finance_date
      datatype: Date
      bindings:
        - {dataset: financial_performance, field: finance_dates.finance_date, path: [ financial_performance_date ]}
        - {dataset: pnl_statement, field: finance_dates.finance_date, path: [ pnl_statement_date ]}
        - {dataset: variance_drivers, field: finance_dates.finance_date, path: [ variance_drivers_date ]}
      time:
        nativeGrain: day
        grains: [ day, week, month, quarter, year ]
        calendar: iso8601
    - name: finance_month
      datatype: String
      bindings:
        - {dataset: financial_performance, field: finance_dates.finance_month, path: [ financial_performance_date ]}
        - {dataset: pnl_statement, field: finance_dates.finance_month, path: [ pnl_statement_date ]}
        - {dataset: variance_drivers, field: finance_dates.finance_month, path: [ variance_drivers_date ]}
    - name: segment
      datatype: String
      bindings:
        - {dataset: financial_performance, field: finance_segments.segment, path: [ financial_performance_segment ]}
        - {dataset: pnl_statement, field: finance_segments.segment, path: [ pnl_statement_segment ]}
        - {dataset: variance_drivers, field: finance_segments.segment, path: [ variance_drivers_segment ]}
    - name: country
      datatype: String
      bindings:
        - {dataset: financial_performance, field: finance_countries.country, path: [ financial_performance_country ]}
        - {dataset: pnl_statement, field: finance_countries.country, path: [ pnl_statement_country ]}
        - {dataset: variance_drivers, field: finance_countries.country, path: [ variance_drivers_country ]}
    - name: product
      datatype: String
      bindings:
        - {dataset: financial_performance, field: finance_products.product, path: [ financial_performance_product ]}
        - {dataset: pnl_statement, field: finance_products.product, path: [ pnl_statement_product ]}
        - {dataset: variance_drivers, field: finance_products.product, path: [ variance_drivers_product ]}
    - name: discount_band
      datatype: String
      bindings:
        - {dataset: financial_performance,
            field: finance_discount_bands.discount_band,
            path: [ financial_performance_discount_band ]
          }
    - name: pnl_line
      datatype: String
      bindings:
        - {dataset: pnl_statement, field: pnl_lines.pnl_line, path: [ pnl_statement_line ]}
    - name: line_order
      label: Line
      datatype: Integer
      bindings:
        - {dataset: pnl_statement, field: pnl_lines.line_order, path: [ pnl_statement_line ]}
    - name: variance_driver
      datatype: String
      bindings:
        - {dataset: variance_drivers, field: variance_driver_dimension.driver, path: [ variance_drivers_driver ]}
    - name: driver_order
      datatype: Integer
      bindings:
        - {dataset: variance_drivers,
            field: variance_driver_dimension.driver_order,
            path: [ variance_drivers_driver ]
          }
    - name: week_start
      datatype: Date
      bindings:
        - {dataset: cash_forecast, field: cash_weeks.week_start, path: [ cash_forecast_week ]}
      time:
        nativeGrain: day
        grains: [ day, week, month ]
        calendar: iso8601
    - name: week_label
      label: Week
      datatype: String
      bindings:
        - {dataset: cash_forecast, field: cash_weeks.week_label, path: [ cash_forecast_week ]}
    - name: scenario
      datatype: String
      bindings:
        - {dataset: cash_forecast, field: cash_scenarios.scenario, path: [ cash_forecast_scenario ]}
    - name: scenario_group
      datatype: String
      bindings:
        - {dataset: cash_forecast, field: cash_scenarios.scenario_group, path: [ cash_forecast_scenario ]}
  metrics:
    - name: gross_margin
      type: ratio
      numerator: gross_profit
      denominator: net_sales
      label: Gross margin
      format: percent
    - name: budget_gross_margin
      type: ratio
      numerator: budget_gross_profit
      denominator: budget_sales
      label: Budget gross margin
      format: percent
    - name: ebitda_margin
      type: ratio
      numerator: ebitda
      denominator: net_sales
      label: EBITDA margin
      format: percent
    - name: discount_rate
      type: ratio
      numerator: discounts
      denominator: gross_sales
      label: Discount rate
      format: percent
    - name: revenue_variance
      type: derived
      expression: ${net_sales} - ${budget_sales}
      label: Revenue variance
      unit: USD
      format: currency
    - name: revenue_above_budget
      type: derived
      expression: nullif((${revenue_variance} + abs(${revenue_variance})) / 2, ${revenue_variance} * 0)
      label: Above budget
      description: Positive revenue variance at the current query grain; other outcomes have no bar.
      unit: USD
      format: currency
    - name: revenue_below_budget
      type: derived
      expression: nullif((${revenue_variance} - abs(${revenue_variance})) / 2, ${revenue_variance} * 0)
      label: Below budget
      description: Negative revenue variance at the current query grain; other outcomes have no bar.
      unit: USD
      format: currency
    - name: ebitda_positive_impact
      type: derived
      expression: nullif((${variance_impact} + abs(${variance_impact})) / 2, ${variance_impact} * 0)
      label: Increases EBITDA
      description: Positive EBITDA variance contribution at the current query grain; other outcomes have no bar.
      unit: USD
      format: currency
    - name: ebitda_negative_impact
      type: derived
      expression: nullif((${variance_impact} - abs(${variance_impact})) / 2, ${variance_impact} * 0)
      label: Decreases EBITDA
      description: Negative EBITDA variance contribution at the current query grain; other outcomes have no bar.
      unit: USD
      format: currency
    - name: revenue_variance_percent
      type: ratio
      numerator: revenue_variance
      denominator: budget_sales
      label: Revenue variance %
      format: percent
    - name: gross_profit_variance
      type: derived
      expression: ${gross_profit} - ${budget_gross_profit}
      label: Gross profit variance
      unit: USD
      format: currency
    - name: ebitda_variance
      type: derived
      expression: ${ebitda} - ${budget_ebitda}
      label: EBITDA variance
      unit: USD
      format: currency

Fields

Field Type Required Rules
aiContext AIContext No
apiVersion string Yes one of leapview.dev/v1
kind SemanticModel Yes
metadata SemanticModelMetadata Yes
spec SemanticModelSpec Yes

Nested definitions

AIContext

Field Type Required Rules
examples array of string No
instructions string No
synonyms array of string No

AllSemanticFilter

Field Type Required Rules
all array of SemanticFilter Yes

AnySemanticFilter

Field Type Required Rules
any array of SemanticFilter Yes

DerivedSemanticMetric

Field Type Required Rules
aiContext AIContext No
description string No
expression string Yes
format string No
hidden boolean No
label string No
name string Yes pattern ^[A-Za-z_][A-Za-z0-9_]*$
requiredAccessGrants array of string No
type string Yes one of derived
unit string No

EqualsSemanticFilter

Field Type Required Rules
aiContext AIContext No
field string Yes pattern ^[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*$
operator string Yes one of equals
path array of string No
value SemanticLiteral Yes

FieldsSemanticRelationshipEndpoint

Field Type Required Rules
dataset string Yes pattern ^[A-Za-z_][A-Za-z0-9_]*$
fields array of string Yes

GreaterThanOrEqualSemanticFilter

Field Type Required Rules
aiContext AIContext No
field string Yes pattern ^[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*$
operator string Yes one of greater_than_or_equal
path array of string No
value SemanticLiteral Yes

GreaterThanSemanticFilter

Field Type Required Rules
aiContext AIContext No
field string Yes pattern ^[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*$
operator string Yes one of greater_than
path array of string No
value SemanticLiteral Yes

InSemanticFilter

Field Type Required Rules
aiContext AIContext No
field string Yes pattern ^[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*$
operator string Yes one of in
path array of string No
value array of SemanticLiteral Yes

IsNotNullSemanticFilter

Field Type Required Rules
aiContext AIContext No
field string Yes pattern ^[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*$
operator string Yes one of is_not_null
path array of string No

IsNullSemanticFilter

Field Type Required Rules
aiContext AIContext No
field string Yes pattern ^[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*$
operator string Yes one of is_null
path array of string No

LessThanOrEqualSemanticFilter

Field Type Required Rules
aiContext AIContext No
field string Yes pattern ^[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*$
operator string Yes one of less_than_or_equal
path array of string No
value SemanticLiteral Yes

LessThanSemanticFilter

Field Type Required Rules
aiContext AIContext No
field string Yes pattern ^[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*$
operator string Yes one of less_than
path array of string No
value SemanticLiteral Yes

LocalSemanticDimension

Field Type Required Rules
aiContext AIContext No
datatype string No one of String, Integer, Decimal, Float, Boolean, Date, Time, DateTime, DateTimeTz, Opaque
description string No
field string No pattern ^[A-Za-z_][A-Za-z0-9_]*$
label string No
name string Yes pattern ^[A-Za-z_][A-Za-z0-9_]*$
requiredAccessGrants array of string No
time SemanticTimeSemantics No

NamedSemanticFilter

Field Type Required Rules
definition SemanticFilter Yes
name string Yes pattern ^[A-Za-z_][A-Za-z0-9_]*$

NamedSemanticRelationshipEndpoint

Field Type Required Rules
dataset string Yes pattern ^[A-Za-z_][A-Za-z0-9_]*$
entity string Yes pattern ^[A-Za-z_][A-Za-z0-9_]*$

NotEqualsSemanticFilter

Field Type Required Rules
aiContext AIContext No
field string Yes pattern ^[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*$
operator string Yes one of not_equals
path array of string No
value SemanticLiteral Yes

NotInSemanticFilter

Field Type Required Rules
aiContext AIContext No
field string Yes pattern ^[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*$
operator string Yes one of not_in
path array of string No
value array of SemanticLiteral Yes

NotSemanticFilter

Field Type Required Rules
not SemanticFilter Yes

RatioSemanticMetric

Field Type Required Rules
aiContext AIContext No
denominator string Yes pattern ^[A-Za-z_][A-Za-z0-9_]*$
description string No
format string No
hidden boolean No
label string No
name string Yes pattern ^[A-Za-z_][A-Za-z0-9_]*$
numerator string Yes pattern ^[A-Za-z_][A-Za-z0-9_]*$
requiredAccessGrants array of string No
type string Yes one of ratio
unit string No

ResourceProvenance

Field Type Required Rules
origin string No
path string No
source string No

SemanticAccessFilter

Field Type Required Rules
field string Yes pattern ^[A-Za-z_][A-Za-z0-9_]*$
userAttribute string Yes pattern ^[A-Za-z_][A-Za-z0-9_]*$

SemanticAccessGrant

Field Type Required Rules
allowedValues SemanticAllowedValues Yes
name string Yes pattern ^[A-Za-z_][A-Za-z0-9_]*$
userAttribute string Yes pattern ^[A-Za-z_][A-Za-z0-9_]*$

SemanticAllowedValues

Field Type Required Rules

SemanticDataset

Field Type Required Rules
accessFilters array of SemanticAccessFilter No
aiContext AIContext No
defaultTimeDimension string No pattern ^[A-Za-z_][A-Za-z0-9_]*$
description string No
dimensions array of LocalSemanticDimension No
displayName string No
metrics array of SimpleSemanticMetric No
model string Yes pattern ^[A-Za-z_][A-Za-z0-9_.-]*$
name string Yes pattern ^[A-Za-z_][A-Za-z0-9_]*$
requiredAccessGrants array of string No

SemanticDimension

Field Type Required Rules
aiContext AIContext No
bindings array of SemanticDimensionBinding Yes
datatype string No one of String, Integer, Decimal, Float, Boolean, Date, Time, DateTime, DateTimeTz, Opaque
description string No
label string No
name string Yes pattern ^[A-Za-z_][A-Za-z0-9_]*$
requiredAccessGrants array of string No
time SemanticTimeSemantics No

SemanticDimensionBinding

Field Type Required Rules
dataset string Yes pattern ^[A-Za-z_][A-Za-z0-9_]*$
field string Yes pattern ^[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*$
path array of string No

SemanticFilter

Field Type Required Rules

SemanticLiteral

Field Type Required Rules

SemanticMetric

Field Type Required Rules

SemanticMetricDerivedVariant

Field Type Required Rules
type string Yes one of derived

SemanticMetricRatioVariant

Field Type Required Rules
type string Yes one of ratio

SemanticModel

Field Type Required Rules
aiContext AIContext No
apiVersion string Yes one of leapview.dev/v1
kind SemanticModel Yes
metadata SemanticModelMetadata Yes
spec SemanticModelSpec Yes

SemanticModelMetadata

Field Type Required Rules
description string No
displayName string No
documentation string No
domain string No
id string Yes pattern ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
name string Yes pattern ^[A-Za-z_][A-Za-z0-9_.-]*$
owner string No
provenance ResourceProvenance No
tags array of string No

SemanticModelSpec

Field Type Required Rules
accessGrants array of SemanticAccessGrant No
datasets array of SemanticDataset Yes
dimensions array of SemanticDimension No
filters array of NamedSemanticFilter No
metrics array of SemanticMetric No
relationships array of SemanticRelationship No

SemanticRelationship

Field Type Required Rules
aiContext AIContext No
description string No
from SemanticRelationshipEndpoint Yes
name string Yes pattern ^[A-Za-z_][A-Za-z0-9_]*$
to SemanticRelationshipEndpoint Yes

SemanticRelationshipEndpoint

Field Type Required Rules

SemanticTimeSemantics

Field Type Required Rules
calendar string No
grains array of string Yes
nativeGrain string Yes one of second, minute, hour, day, week, month, quarter, year
timezone string No

SimpleSemanticMetric

Field Type Required Rules
agg string Yes one of sum, count, count_distinct, avg, min, max
aiContext AIContext No
description string No
empty string No one of zero, null
field string No pattern ^[A-Za-z_][A-Za-z0-9_]*$
format string No
hidden boolean No
label string No
name string Yes pattern ^[A-Za-z_][A-Za-z0-9_]*$
requiredAccessGrants array of string No
timeDimension string No pattern ^[A-Za-z_][A-Za-z0-9_]*$
type string Yes one of simple
unit string No
where array of string No