Business definitions

Documents tell you what's written down. Definitions tell you what your organization has decided — and that's usually the part nobody wrote down, or wrote down four times differently.

A definition is an entry your team owns, approves and versions. Once approved, it governs answers: ask what a term means and you get the official answer, not the closest paragraph.

The four kinds

Kind	What it captures	Example
metric	A business metric and how it's calculated	revenue: recognized revenue per contract, excluding promotional credits
entity	The canonical source for a concept	customer: the accounts table in billing is the official source; CRM records are a mirror
rule	Conditional knowledge that lives in people's heads	new USCAN deals since 2025 are in Affinity; earlier global leads are in the CRM
glossary	A domain term with its aliases	churn: a cancellation effective at the end of the billing period

Rules are the ones teams underestimate. They're the answers you'd give a new hire in their first week — the conditional, "it depends on the year and the region" knowledge that no document states and every correct answer needs.

Creating one

curl -X POST $RENBASE_API/v1/context \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"kind": "metric",
       "name": "revenue",
       "aliases": ["net revenue", "recognized revenue"],
       "body": "Recognized revenue per contract, excluding promotional credits.",
       "code": "select sum(amount_eur) from fct_revenue",
       "scope": {"region": "EMEA", "from": "2025-01-01"},
       "approve": true}'

• aliases are how people actually say it. They resolve to the same entry.
• code is optional and holds the query or reference that materializes the metric, for the humans and agents that need it.
• scope records the conditions under which the definition is valid — a region, a system, a date range.
• approve: true publishes it immediately. Omit it and the entry waits in the review queue.

Review and approval

Anything a machine proposes arrives as a draft, and drafts don't affect answers.

# The review queue
curl "$RENBASE_API/v1/context?status=draft" -H "Authorization: Bearer $ADMIN_TOKEN"

# Approve or reject
curl -X POST $RENBASE_API/v1/context/{id}/approve -H "Authorization: Bearer $ADMIN_TOKEN"
curl -X POST $RENBASE_API/v1/context/{id}/reject  -H "Authorization: Bearer $ADMIN_TOKEN"

Editing an approved entry (PATCH) creates a new approved version that supersedes the previous one. Nothing is overwritten and the history stays available.

Renbase Studio has the same queue with a review interface, which is where most teams do this.

How definitions reach answers

When a question mentions an approved entry by name or alias, that entry is resolved exactly and enters the answer as a fixed source — ahead of any search. It's a lookup, not a similarity match: for "what does revenue mean here?" you need the governed answer, not the most similar paragraph.

For questions that don't name anything precisely, definitions still compete alongside documents in the search, so a well-written definition surfaces on its own merits.

To resolve a term without asking a full question — cheap, and it consumes no credits:

curl -G $RENBASE_API/v1/context/resolve --data-urlencode 'q=what is revenue?' \
  -H "Authorization: Bearer $RENBASE_KEY"

Conflicts

Two approved entries for the same term with overlapping scope are marked as conflicting, and neither is hidden. An answer touching that term returns both, with their provenance, and says they disagree.

This is deliberate. A system that silently picks one is a system that will confidently give the finance answer to a product question. Surfacing the disagreement is what lets your team fix it.

Freshness

Every entry carries the date it was last verified against its source, and that date travels in the citation. When a definition's source disappears, the entry is flagged stale: it keeps working, but answers warn that it may be out of date. Removing it is a human decision, never an automatic one.

Importing what you already have

Definitions rarely start from scratch. If your data tooling already documents models, metrics and columns, you can import them: the extraction produces one candidate per model, metric or documented term.

curl -X POST $RENBASE_API/v1/context/import \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"candidates": [{"kind": "entity", "name": "orders", "body": "…", "source": {"key": "model.orders"}}]}'

Three properties matter in practice:

• Imports never approve. Everything arrives as a draft. The tool proposes; your team decides.
• Re-importing is safe. Each candidate carries a stable key and a content fingerprint: unchanged content is re-verified rather than duplicated, changed content becomes a draft of the next version.
• dry_run shows the plan without writing anything.

Your organization's data platform connectors — including a client-side one that reads a warehouse schema without those credentials ever leaving your network — are set up with our team during onboarding.

Turning complaints into rules

When someone marks an answer as unhelpful and explains why, that correction is the most valuable input you have. The refinement queue lists them, and a correction can be promoted directly into a rule:

curl $RENBASE_API/v1/feedback -H "Authorization: Bearer $ADMIN_TOKEN"

curl -X POST $RENBASE_API/v1/feedback/{id}/promote \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"approve": true}'

Every bad answer someone corrects improves all the answers after it, and the record shows who decided what.