Vocabulary¶
Every annotation any active extension permits, generated from the profiles themselves. If an annotation is not listed here, rule V001 rejects it.
Annotations on a table¶
| Annotation | Range | Meaning |
|---|---|---|
varda:fact_type |
FactType |
The temporal shape of a fact table. Facts only. |
varda:grain_statement |
string |
What exactly one row of this table represents, as a sentence. Required on facts, alongside varda:grain. Conventionally phrased "one row per ...". Checked for being a sentence and nothing further: varda:grain carries the half of the claim a validator can test, and this carries the half it cannot. The sentence is not redundant with the columns. It states why those columns, and what a row means to somebody reading the model rather than querying it. A fact table whose grain nobody can state in a sentence is one whose double counting nobody can rule out, and the discipline of writing it is most of the value. |
varda:grain |
string, list |
The columns at which rows of this table are unique — the set that together identifies exactly one row. Required on facts. This is the grain proper: in every formal treatment of dimensional modeling the grain is the column set that identifies a row. Every entry must name a column of this table, and each must be a foreign key or a degenerate dimension: those are the columns that locate a row in the model's dimensional space. A measure cannot be part of a grain, because a grain is what a row is, not what it records. And each should be required: SQL counts NULLs as distinct, so a uniqueness constraint over a column that may be absent does not hold for the rows that lack it. Stating the grain as columns is what makes it checkable — a validator can test the claim, and a generator can emit it as a uniqueness constraint the database enforces. |
varda:hierarchies |
Hierarchy, list |
Named drill paths over this dimension's columns. Dimensions only. Each hierarchy lists its levels from least to most granular — [country, region, city], not the reverse. A column may appear in several hierarchies, which is how a date dimension carries both a calendar path and a week path: weeks do not nest inside months, so they are separate hierarchies rather than one chain. A level names what a reader sees when they drill, so it must be a column somebody can read. A surrogate key or a foreign key is a fine identity and an unreadable label — nobody drills into 4718 — so neither may name a level. Where the coarser levels are their own tables, write foreign_key.column to reach the readable column through the key: country_key.country_name rather than country_key. Both halves are checked — the near column must be a foreign key of this table, and the far one a column of the dimension it points at. A level names a member of the level; whether it also identifies one is a separate question. month_name holds "January", which every year has, and city_name holds "Springfield", which several states have. Both describe the path correctly and neither can be grouped by alone. Prefer a column that identifies where one exists naturally — year_month in a date dimension — and expect anything grouping by a level that does not to carry the coarser levels with it. Reaching through a foreign key avoids the question, because the key has already picked one row out. That each level determines the one above it — that every city is in exactly one region — is asserted here and not checked, because it is a claim about data rather than about the schema. What is checked is that the levels are real, distinct, and the kind of column a level can be. Only fixed-depth paths where each level rolls up into exactly one parent. A hierarchy whose branches differ in depth, whose levels can be skipped, or where a child has several parents is a bridge table. |
varda:physical_name |
string |
The table name to emit, when it differs from the class name. Without it, generators derive a physical name from the class name. |
varda:role |
TableRole required |
What part this table plays. Required on every table. |
varda:scd |
SlowlyChangingType |
How this dimension responds to source changes. Dimensions only. Declared on the table rather than per column, because a mixed dimension — some attributes type 1, others type 2 — is a genuinely harder object that this core deliberately does not model. Split it into two dimensions, or handle it in an extension. |
Annotations on a column¶
| Annotation | Range | Meaning |
|---|---|---|
varda:additivity |
Additivity |
How this measure may be aggregated. Required on every measure. |
varda:lands_on |
ReferencedKey |
Which key of its target this foreign key holds: the surrogate key, which is the default, or the durable key. Foreign keys only, and DURABLE_KEY only where the target declares one. The durable key reaches an entity rather than one version of it, so a fact carrying both kinds of key can report every event by the attributes in force when it happened or by those in force now. |
varda:max_length |
integer |
The widest value this column holds, in characters. Emitted as the length of the SQL type: VARCHAR(80). String columns only — string, uri, uriorcurie, ncname. A length on a date parameterizes nothing. Optional, and there is no default. A column declaring none emits a bare VARCHAR, which is unbounded in PostgreSQL and DuckDB and means VARCHAR(1) in SQL Server. Varda states the width the model gave it and invents nothing, because a default width is a number nobody chose appearing in a schema everybody trusts. |
varda:physical_name |
string |
The column name to emit, when it differs from the slot name. |
varda:precision |
integer |
How many significant digits this column keeps, counting both sides of the decimal point. Emitted as the first parameter of the SQL type: the 18 in NUMERIC(18, 2). Decimal columns only. A float has no exact precision to declare — that is what makes it a float. Optional. A bare NUMERIC is exact and unconstrained in PostgreSQL and DECIMAL(18, 3) in DuckDB, where a unit price of 0.123456 is stored as 0.123 and no error is raised. V707 asks every decimal measure to say what it keeps. |
varda:previous_of |
string |
The attribute of this table whose value before its last change this column holds: prior_category beside category, so a report can show either the new grouping or the one it replaced. Kimball's type 3 — one step of history, in a column rather than a row. An attribute naming another attribute of the same dimension, storing the same type at least as wide. Not on a fact or a bridge, whose rows are not revised, nor on a TYPE_0 dimension, which keeps every original value. Several may chain — prior_prior_category naming prior_category — but not in a cycle. |
varda:references |
string |
The name of the class this foreign key points at. Required on every column whose role is FOREIGN_KEY, and checked: it must name a class that exists and that is a dimension. The table holding the key may be any of the three. |
varda:role |
ColumnRole required |
What part this column plays. Required on every column. |
varda:scale |
integer |
How many of this column's digits fall after the decimal point. Emitted as the second parameter of the SQL type: the 2 in NUMERIC(18, 2). Decimal columns only, and needs a varda:precision beside it — there is no NUMERIC(, 2) to emit. May be zero, which is a whole number stored as a decimal and not a mistake. |
varda:semi_additive_aggregate |
SemiAdditiveAggregate |
What this measure takes across varda:semi_additive_over in place of the sum: the last value, the first, the lowest, the highest or the average. Semi-additive measures only. Not required, and asked for: without it every consumer decides for itself whether a month of balances is the closing one or the average, and two reports answer one question two ways. |
varda:semi_additive_over |
string, list |
The foreign keys across which this measure may NOT be summed — almost always the date alone, written as one name. Required when additivity is SEMI_ADDITIVE, and checked against the table's actual foreign keys, because naming a dimension the fact does not have is a constraint that silently never applies. Several where several apply: a headcount snapshot taken per month and per scenario sums across neither. |
Structured values¶
The shapes an annotation's value takes when its range is not a scalar.
Hierarchy¶
One named drill path over a dimension's columns. Not an annotation class: it carries no varda:applies_to, because it is the range of varda:hierarchies rather than something a model annotates directly.
| Key | Range | Meaning |
|---|---|---|
name |
string required |
What this path is called, unique within the table. Names it rather than numbering it, because a dimension with a calendar path and a fiscal path needs the reader to know which is which. |
description |
string |
What this path is for, when the name alone does not carry it. A dimension with several paths is where this earns its place: merchandise and finance name two ways of rolling the same products up, and which one a reader wants is not decidable from the names. |
kind |
HierarchyKind |
How this path is stored: LEVELS, the default, PARENT_CHILD or BRIDGED. Each kind uses its own fields and no other's. |
levels |
Level, list |
The levels, from least to most granular. LEVELS only, and required there. At least two: one level is not a hierarchy, it is a column. Each is written as a column name — city_name, or country_key.country_name to reach through a foreign key — or as a mapping carrying column and key when what names the level is not what tells its members apart. |
strict |
boolean |
Whether each level's own key tells its members apart, so that every member sits under exactly one parent — brand "Acme" is one brand, in one category. False by default, because a plain level's column usually names a member only under its parent: several states have a Springfield, and a city is identified by its state and its name together. Declared, it is checked: sql/expectations.sql reports every member found under two parents. Not for a type-2 dimension, whose rows are versions; a city moving region there is history. |
complete |
boolean |
Whether every row holding a level holds the level above it. True by default, and checked in sql/expectations.sql: a product with a brand and no category drops out of every roll-up by category. False for a path that may skip levels — a store reporting straight to its country, with no region — which says so instead of being reported for it. |
parent |
string |
The foreign key into this same table naming each row's parent. PARENT_CHILD only, and required there. Null for a root. |
bridge |
string |
The bridge holding this tree flattened, a row per ancestor and descendant. BRIDGED only, and required there. |
ancestor |
string |
The bridge's foreign key to the ancestor, into this dimension. BRIDGED only, and required there. |
descendant |
string |
The bridge's foreign key to the descendant, into this dimension. BRIDGED only, and required there. |
depth |
string |
The bridge's column counting the steps from ancestor to descendant: 0 for a member and itself, 1 for its parent. BRIDGED only. Optional, and checked where declared. |
Level¶
One step of a drill path. Written as a bare column name wherever that column identifies the level's members, which is the common case. The mapping form exists for the case it does not. Declared as a class so the shape is documented and machine-readable, not because LinkML enforces it: annotation values are opaque to LinkML, so a level naming a field this class does not have is caught by Varda's own rules rather than by the schema. varda:shorthand is what makes the bare form legal: a scalar written where a Level is expected is its column. A structured range declaring no shorthand must be written as a mapping, and V007 says so.
| Key | Range | Meaning |
|---|---|---|
column |
string required |
The column that names this level to a reader. Either a column of the table the hierarchy is declared on, or foreign_key.column to reach one through a foreign key. |
key |
string |
The column that tells one member of this level from another under the same parent, when that is not the column naming it. A level showing product_name where two products share a name is identified by sku. Rarely needed. It defaults to the foreign key for a level reached through one and to the naming column otherwise, and a level's full identity is that key preceded by the key of every coarser level — city_name holds "Springfield" for cities in three states, and country, state and city together hold one of them. That path is what the hierarchy already says, so it is never written out. Asserted and not checked. Varda checks the column exists and is the kind that can identify something; whether members are actually distinct is a claim about data. |
Enumerations¶
These are closed. An extension may not add a value to one — see Extending.
TableRole¶
What part a class plays in the dimensional model. Every class carrying Varda annotations must declare exactly one.
| Value | Meaning |
|---|---|
FACT |
A measurement event table. Has a declared grain, foreign keys to dimensions, and zero or more measures. Never the target of another table's foreign key. |
DIMENSION |
Descriptive context. Has one surrogate key, one or more natural key columns, and attributes that are almost always textual or categorical. Referenced by facts. |
BRIDGE |
Resolves a many-to-many between a fact and a dimension, or a multi-valued dimension attribute. Carries an allocation factor when the many-to-many is weighted. |
ColumnRole¶
What part a slot plays inside its table. Every slot of a class carrying Varda annotations must declare exactly one. This is the most valuable annotation in the profile: it is what turns a flat list of columns into a structure that generators and validators can reason about.
| Value | Meaning |
|---|---|
SURROGATE_KEY |
The meaningless integer or hash primary key of a dimension. Exactly one per dimension. |
NATURAL_KEY |
A column carrying the business identity of a dimension row. Together the natural key columns — plus, for a type-2 dimension, the validity window — must be unique. |
DURABLE_KEY |
The identity of an entity that outlives every version of it: one value per customer however many rows a type-2 dimension holds for them, assigned by the warehouse and kept when the natural key itself changes. Dimensions only, at most one each. What lets a fact reach the dimension as it is now rather than as it was — Kimball's type 7. A fact carries the surrogate key for the version in force when the event happened, and, beside it, a foreign key with varda:lands_on: DURABLE_KEY; joining on the second and the current flag gives every event today's attributes. Unique version for version, as a natural key is, and Varda derives that uniqueness the same way. |
FOREIGN_KEY |
A reference to the surrogate key of a dimension, or to its durable key where varda:lands_on says so. Must declare varda:references, and must store the same type as the key it names. Legal on any table. A fact referencing its dimensions is the common case, and a dimension referencing another is a snowflake — which is why a hierarchy level may be written country_key.country_name, to reach a readable column through the key. What a foreign key may not do is point at a fact: that join is fact-to-fact, the grain of the result is neither table's, and no aggregate over it is safe. Nor, today, at a bridge. A bridge carries no surrogate key, so a reference to one has nothing to land on and no generator can emit it; V406 refuses it rather than letting it pass unenforced. Required on a fact, as a warning. A fact row with no key for a dimension drops out of every inner join to it; point it at an unknown-member row instead. |
MEASURE |
A numeric quantity that is aggregated. Must declare varda:additivity. Lives on a fact or a bridge, never a dimension. |
ATTRIBUTE |
Descriptive context, grouped and filtered on but not summed. The default role for a dimension column. |
DEGENERATE_DIMENSION |
An identifier that lives on the fact with no dimension table of its own — an order number, a ticket reference. Fact tables only. |
VERSION_START |
The instant from which this version of the row is the one in force. Dimensions with varda:scd: TYPE_2 only. Named for the version rather than for validity on purpose. In practice this column usually records when the warehouse observed the change rather than when the change was true in the business — dbt's snapshots and Data Vault's LOAD_DATE both work this way, whatever they are called. Varda does not distinguish the two, because separating business validity from load time is bitemporality and that is out of scope here. The period is closed at the start and open at the end, following SQL:2011: a row is in force from this instant up to but not including VERSION_END. That convention is what stops consecutive versions overlapping at their boundary. Ontology term: time:hasBeginning |
VERSION_END |
The instant at which this version stopped being the one in force, exclusive. Dimensions with varda:scd: TYPE_2 only. Optional, and genuinely so. A great many type-2 dimensions store only the start and derive the end from the next version's start; Data Vault virtualizes it as a view over an insert-only satellite. Requiring it would reject correct designs, so nothing does. Ontology term: time:hasEnd |
IS_CURRENT |
Flags the version in force now. Dimensions with varda:scd: TYPE_2 only. Derivable from the period, and materialized anyway almost everywhere, because the alternative is a null test or a far-future sentinel in every query that wants today's row. |
VERSION_NUMBER |
A monotonic counter distinguishing versions of one natural key, for dimensions that version without timestamps at all. The current version is the highest. Dimensions with varda:scd: TYPE_2 only. |
ReferencedKey¶
Which key of its target a foreign key holds the value of.
| Value | Meaning |
|---|---|
SURROGATE_KEY |
The target's surrogate key: one row, the version in force when the referencing row was written. What every foreign key lands on unless it says otherwise. |
DURABLE_KEY |
The target's durable key: one entity, whichever of its versions is asked for. Repeated once per version of a type-2 dimension, so no FOREIGN KEY constraint can name it; the assertions check that every value names some row. |
Additivity¶
How a measure may be aggregated across dimensions. Required on every measure, because the wrong answer here is the single most expensive class of error a dimensional model produces: silently summing something that must not be summed yields a number that looks fine and is wrong.
| Value | Meaning |
|---|---|
ADDITIVE |
May be summed across every dimension of its fact. Sales amount, quantity, cost. |
SEMI_ADDITIVE |
May be summed across some dimensions but not others — almost always not across time. Account balance, inventory level, headcount. Must declare varda:semi_additive_over, and should declare varda:semi_additive_aggregate. |
NON_ADDITIVE |
May not be summed across any dimension. Ratios, percentages, unit prices, temperatures. Aggregate the components and recompute. |
SemiAdditiveAggregate¶
What a semi-additive measure takes across the dimensions it may not be summed over, in place of the sum. Stock on hand across a month is not thirty days of stock added up; it is the stock on the last day, or the average day, and which one is a decision the model makes once rather than one every report makes again. Across the other dimensions the measure still sums. Total stock on the last day of the month is the sum across stores of each store's stock on that day.
| Value | Meaning |
|---|---|
LAST |
The value at the latest member in range — a closing balance, stock at the end of the period. Latest by the dimension's own order, which for a date is the calendar; needs exactly one dimension to order by. |
FIRST |
The value at the earliest member in range — an opening balance. Needs exactly one dimension to order by. |
MIN |
The lowest value across the members in range — the low point of a balance over a month. |
MAX |
The highest value across the members in range — peak headcount, the most stock held. |
AVERAGE |
The mean across the members in range — an average daily balance. Over the members present in the rows: a day with no row is not a day with zero, and a fact that skips days averages over the days it has. |
HierarchyKind¶
How a drill path is stored. Each has one relational form, after Malinowski and Zimányi's classification, and a generator or a query tool needs to know which one it is reading.
| Value | Meaning |
|---|---|
LEVELS |
A fixed number of levels, one column each — country, region, store. The default. |
PARENT_CHILD |
A tree of any depth, each row naming its parent through a foreign key into its own table — an employee and their manager. Declares parent. |
BRIDGED |
The same tree flattened into a bridge holding a row for every ancestor and descendant, with the depth between them, so that a query reaches every descendant with one join rather than a recursion. Declares bridge, ancestor and descendant, and should declare depth. |
SlowlyChangingType¶
How a dimension responds when a source attribute changes. Kimball's numbering, restricted to the three types that are common enough to generate for.
| Value | Meaning |
|---|---|
TYPE_0 |
Retain original. The value is written once at first load and never updated, whatever the source says afterwards. |
TYPE_1 |
Overwrite. No history is kept; the row shows the current value. |
TYPE_2 |
Add a row. History is preserved by versioning: a new row per change, bounded by a validity window and marked with a current flag. |
FactType¶
The temporal shape of a fact table, which determines how it is loaded and what its grain sentence must say.
| Value | Meaning |
|---|---|
TRANSACTION |
One row per event, at the moment the event occurs. Insert-only. |
PERIODIC_SNAPSHOT |
One row per entity per regular interval, whether or not anything happened. Insert-only, predictable size. |
ACCUMULATING_SNAPSHOT |
One row per tracked item, updated in place as it passes milestones. The only fact shape that is routinely updated after insert. |
FACTLESS |
One row per event or condition, carrying no measure — coverage, eligibility, attendance. Counted rather than summed. |