Varendo

Semantic contracts

Separate technical field types from business definitions, units, aggregation, grain, and temporal policy.

Semantics are what fields mean — not their types. “Number” cannot tell you whether a value is a sum, an average, a ratio, a currency, or a trend. Semantic metadata stops a valid-looking query from making an invalid claim.

Preserve meaning in the Result

  • Stable entity identity and authorized population scope.
  • Row or aggregation grain.
  • Unit, precision, null behavior, and completeness.
  • Temporal field, calendar, timezone, and bucket grain when applicable.
  • Catalog, source, policy, and Result revisions.
  • Lineage from registered meaning and query operations.

Read a registered meaning

This is the month-end headcount meaning from the maintained quickstart fixture. It is a reviewable contract, not a SQL fragment. It fixes the output kind and grain, the aggregation rule, and the missing-value policy.

resource.ts

TypeScript example
const workforceHeadcount = defineResource({
  id: 'workforce-headcount',
  // schema, identity, fields…
  meanings: [
    {
      id: 'month-end-headcount',
      revision: '1',
      label: 'Month end headcount',
      explanation: 'Employees active at the end of each month. Never sum across time.',
      output: { value: 'integer', nullable: false, grain: ['month'] },
      implementation: {
        kind: 'expression',
        expression: {
          kind: 'call',
          function: { id: 'core.aggregate.sum', revision: '1' },
          arguments: [{ kind: 'field', ref: 'headcount' }],
        },
      },
      dependencies: [],
      functionRegistryDigest: 'core-query-2',
      origin: 'manual',
      lifecycle: 'active',
      scope: 'workspace',
      authority: 'approved',
      aggregation: 'semi-additive', // compare across months; never total them
      aggregationDimensions: ['month'],
      missingPolicy: 'reject', // missing rows fail instead of faking coverage
    },
  ],
});

Compare additive and ratio meanings

Absence days can be summed. Absence rate is a ratio with a defined numerator, denominator, population, period, and precision. Varendo accepts analysis only when the requested meaning and grain are registered and compatible.

Respect missing data

Null is not zero. Partial is not exact. Sampled is not complete. The Result contract keeps these distinctions available to the recipe, so the UI cannot silently overstate evidence.