# Semantic YAML reference

> Every field the Flax semantic layer supports, from model and column metadata to the flax extension

*[View this page in the Flax docs](https://flax-analytics.com/docs/modeling/semantic-yaml-reference)*

This is the reference for the Flax semantic-layer YAML: the dbt-compatible file shape and the `flax:` extension that adds dimensions, measures, joins, and row-level security. It is grounded in `packages/semantic-spec`. Use it to look up field names, types, and constraints.

## File shape

A Flax model file is a dbt schema file. The top level is `version: 2` and a `models:` list. Each model has dbt-native `name`, `description`, and `columns`, plus a Flax-specific `flax:` block.

```yaml
version: 2

models:
  - name: orders
    description: One row per order placed in the store.
    columns:
      - name: order_id
        description: Primary key for the order.
      - name: amount
        description: Gross order amount.
    flax:
      primary_key: order_id
      dimensions: [ ... ]
      measures: [ ... ]
      joins: [ ... ]
      access_filters: [ ... ]
```

Because everything Flax-specific is namespaced under `flax:`, the same file remains valid to dbt. See [dbt projects](/docs/connections/dbt-projects) for connecting an existing project.

## The `flax:` extension

| Field | Type | Description |
| --- | --- | --- |
| `primary_key` | string | Column uniquely identifying a base row. Enables correct (symmetric) counts and sums over fan-out joins. |
| `dimensions` | list | Attributes to group and filter by. |
| `measures` | list | Aggregations. |
| `joins` | list | Relationships to other models. |
| `access_filters` | list | Mandatory row-level-security predicates. |

## Dimensions

Fields for each item in `dimensions`. Required: `name`, `type`, `sql`.

| Field | Type | Description |
| --- | --- | --- |
| `name` | string | Field identifier. |
| `label` | string | Display name in the UI. |
| `description` | string | Documentation for the field. |
| `type` | enum | One of `string`, `number`, `boolean`, `time`. |
| `sql` | string | SQL expression. `${column}` is a column on this model; `${model.column}` a joined model's column. |
| `time_grains` | list | For `time` dimensions: any of `day`, `week`, `month`, `quarter`, `year`. |
| `hidden` | boolean | Hide from the explore picker (default `false`). |

```yaml
dimensions:
  - name: order_date
    label: Order date
    type: time
    time_grains: [day, week, month, quarter, year]
    sql: ${created_at}
```

## Measures

Fields for each item in `measures`. Required: `name`, `type`.

| Field | Type | Description |
| --- | --- | --- |
| `name` | string | Field identifier. |
| `label` | string | Display name in the UI. |
| `description` | string | Documentation for the field. |
| `type` | enum | `count`, `count_distinct`, `sum`, `average`, `min`, `max`, `median`, `percentile`, `number`. |
| `percentile` | number | Fraction 0–1 for `type: percentile` (e.g. `0.25` for Q1). |
| `sql` | string | Expression to aggregate. Use `"*"` with `type: count` for a row count. |
| `filters` | list of strings | SQL boolean expressions AND-ed into the aggregation. |
| `hidden` | boolean | Hide from the explore picker (default `false`). |

```yaml
measures:
  - name: completed_revenue
    label: Completed revenue
    type: sum
    sql: ${amount}
    filters:
      - ${status} = 'complete'
  - name: p90_amount
    type: percentile
    percentile: 0.9
    sql: ${amount}
```

## Joins

Fields for each item in `joins`. Required: `name`, `sql_on`.

| Field | Type | Description |
| --- | --- | --- |
| `name` | string | Name of the model to join. |
| `type` | enum | `left` (default), `inner`, `full`, `right`. |
| `relationship` | enum | `one_to_one`, `many_to_one`, `one_to_many`, `many_to_many`. |
| `sql_on` | string | Join predicate, e.g. `${orders.customer_id} = ${customers.customer_id}`. |

## Access filters

Fields for each item in `access_filters`. Required: `sql`, `attribute`. See [Row-access filters](/docs/modeling/row-access-filters).

| Field | Type | Description |
| --- | --- | --- |
| `sql` | string | Org-authored SQL expression (e.g. `${region}`) compared as text to the caller's attribute values. |
| `attribute` | string | Principal attribute key the allowed values come from (e.g. `region`). |

```yaml
access_filters:
  - sql: ${region}
    attribute: region
```

> [!NOTE]
> The `flax:` block rejects unknown keys — the JSON Schema sets `additionalProperties: false` on every object. A typo in a field name is a validation error, not a silent no-op.

## Related

- [Dimensions and measures](/docs/modeling/dimensions-and-measures)
- [Relationships and joins](/docs/modeling/relationships-and-joins)
- [Row-access filters](/docs/modeling/row-access-filters)
- [SQL compilation](/docs/modeling/sql-compilation)