Documentation

Community documentation

Reference data, governed and ready to consume.

Install and operate refrncr Community, define datasets, manage controlled publications and consume Current or historical data through the read-only REST API.

Community editionPython 3.12+SQLite or PostgreSQLREST API v1

Installation

Public beta installationRefrncr is currently available as a pre-release for pilot users and testers. The --pre option is required until stable version 0.1.0 is released.

The quickest local installation uses pipx. Startup creates a persistent SQLite database and applies all Community migrations before serving requests.

Terminal
pipx install --pre refrncr
refrncr start

Open http://127.0.0.1:8000. Docker and PostgreSQL are not required for this quick start.

Production-style usePostgreSQL is recommended for serious concurrent multi-user operation. Use HTTPS whenever refrncr is exposed through a reverse proxy or beyond the local machine.

Create the first administrator

On a new installation, open /setup and provide an email address, display name and a password of at least 12 characters. The route is disabled after the first user exists.

Alternative CLI setup
refrncr user create-admin \
  --email [email protected] \
  --display-name "Administrator"

The command prompts for a password so it does not enter shell history. Create subsequent users from Settings → Users.

Configuration

Command-line options take precedence over environment variables, which take precedence over defaults.

PurposeOptionEnvironment
Database URL--database-urlREFRNCR_DATABASE_URL
SQLite file--database-path—
Bind address--hostREFRNCR_HOST
HTTP port--portREFRNCR_PORT
Log level--log-levelREFRNCR_LOG_LEVEL
Trusted proxies--trusted-proxyREFRNCR_TRUSTED_PROXIES
API key pepper—REFRNCR_API_KEY_PEPPER

Without REFRNCR_API_KEY_PEPPER, API keys are disabled and the REST API cannot be used. See API keys for how to create and keep the pepper.

Start with SQLite
refrncr start --database-path ./refrncr.db
Start with PostgreSQL
# .env in the folder where you start refrncr
REFRNCR_DATABASE_URL=postgresql+psycopg://refrncr:PASSWORD@localhost/refrncr
REFRNCR_API_KEY_PEPPER=...

refrncr start
Keep secrets out of commands and logsPut passwords and the pepper in environment variables or a protected .env file, not in command-line options. Refrncr reads .env from the folder where it starts and does not override variables that are already set. Do not commit .env.

Datasets

A dataset is a governed reference list with a stable key, current descriptive metadata, one owning team and an ordered schema. Published data is immutable; edits occur in an explicit draft.

Dataset identity

  • Key: stable machine-readable identifier used in URLs and API paths.
  • Name and description: current presentation metadata.
  • Owning team: the team responsible for maintenance and publication.
  • Identifier: one or more eligible fields that uniquely identify every record.

All active Community users can discover and read Current datasets. Creating one requires membership in its owning team; administrators may select any team.

When you create a dataset, you choose one of three dataset types: reference, mapping or hierarchy.

Dataset types

Every dataset type uses the same governance: an owning team, drafts, review, publication with an effective date, audit history, export and the REST API. The type determines how the data is structured and which additional features you get.

Reference datasetMapping datasetHierarchy dataset
RepresentsA list of valuesA translation from source codes to target valuesA tree structure
ExampleCountries, currencies, error codesCost centre to reporting lineOrganisation structure, regions
StructureFields and recordsSource code from a reference dataset plus target fieldsRoot, nodes and optional fields
IdentifierRequired, one or more fieldsThe source codeOptional, for leaves
ViewsTableTable with source and target columnsTree and table
ImportComplete version from CSV or ExcelTarget values from CSV or ExcelEdited export as CSV or Excel
Extra in the API—Lookup by source codeComplete structure

Reference dataset

A reference dataset is a list of values that other systems use to classify data. You define the fields and datatypes and choose which fields together identify each record.

  • Use it for: code tables and master lists such as country codes, currencies, units of measure, general ledger accounts or rates.
  • Choose another type when: you want to relate codes from two systems (mapping dataset) or group values into levels (hierarchy dataset).
  • Example: Countries with the identifier iso_code_3 and the fields name and region.
  • Features: freely defined fields, required and unique fields, search in text values, complete-version import and export.
  • How to apply it: choose Reference dataset, define the fields, mark the identifier fields, add or import records, and publish.

Mapping dataset

A mapping dataset translates the codes of an existing reference dataset into values used by another system. Each source code appears once and has one value per target field. Several source codes may point to the same target value.

  • Use it for: translation tables between applications, such as cost centres to reporting lines or ERP codes to CRM segments.
  • Choose another type when: the list is not based on a reference dataset (reference dataset) or you need to roll up levels (hierarchy dataset). Many-to-many relationships and transformation rules are not supported.
  • Example: Cost centres to reporting, based on the Cost centres dataset, with source code 1001 and target value AMS-SALES.
  • Features: the mapping is pinned to one published version of its source dataset. When the source publishes a new version, the overview shows that the mapping can be updated. When you update it in a draft, existing pairs are kept, new source codes appear without a target and removed codes are marked as deleted. A filter shows the codes that still need a target.
  • How to apply it: choose Mapping dataset, select the source dataset and its source identifier field, add the target fields, enter or import the target values, and publish.

Access to a mapping includes the source codes and context values copied into it. It does not grant access to the source dataset itself.

Hierarchy dataset

A hierarchy dataset describes a tree with one root. Every node has one parent and keeps its identity when it is renamed or moved. Names are unique within the dataset.

  • Use it for: structures you aggregate along, such as an organisation structure, a regional breakdown or a product grouping.
  • Choose another type when: you only need a flat list (reference dataset). To group the same codes in a second way, create a second hierarchy dataset.
  • Example: Organisation structure with Organisation → Commercial → Sales → cost centre 4200.
  • Features: tree and table views, fields for leaves only or for all nodes, and checks for cycles, missing parents and duplicate names before publication. Deleting a node also deletes everything below it.
  • How to apply it: choose Hierarchy dataset, create the root and the nodes below it, add fields if needed, and publish. A consumer reads the complete structure through the API and rolls up totals along it.

Fields and datatypes

Fields define schema, validation, display order and record identity. Refrncr implements nine canonical datatypes.

IDLabelCanonical formIdentifier
stringStringTrimmed NFC UnicodeYes
integerIntegerUngrouped base 10Yes
numberDecimalExact base 10Yes
floatFloatFinite binary64No
booleanBooleantrue or falseYes
dateDateYYYY-MM-DDYes
timeTimeHH:mm:ss[.fraction]Yes
datetimeDateTimeLocal ISO date and timeYes
timestampTimestampUTC timestamp ending in ZYes
Decimal versus FloatUse Decimal when the decimal value must remain exact. Float accepts binary approximation and cannot be part of a record identifier.

Required fields reject null values. Unique fields enforce canonical uniqueness. A datatype can change only while the field has no non-null stored values; refrncr does not perform automatic conversion.

Drafts and versions

A version is a complete, immutable snapshot of a dataset with an effective date. A draft is the working copy in which you prepare the next version. Each version applies from its effective date until the next version takes effect, so on any date exactly one version applies.

  1. Create a draft. Select a published version as its baseline.
  2. Maintain the data. Change fields and records, or import a complete version.
  3. Review changes. Inspect field and record differences against the baseline.
  4. Publish. Choose an effective date and add a release note. The complete snapshot is saved in one transaction.

How versions follow each other

Cost centre CC-1001 moves from Sales to Operations on 1 March 2026 and to Finance on 1 January 2027. Viewed on 1 November 2026:

VersionCC-1001Effective fromApplies untilStatus
1Sales1 Jan 20261 Mar 2026Expired
2Operations1 Mar 20261 Jan 2027Current
3Finance1 Jan 2027—Scheduled

Applies until is the effective date of the next version, and that day already belongs to the next version. On 1 January 2027, Version 3 becomes Current and Version 2 becomes Expired, without any action.

  • Current: the version that applies today. Reads use it unless you ask for another date or version.
  • Scheduled: published, with an effective date in the future.
  • Expired: applied earlier and has been replaced by a later version.
  • Cancelled: a Scheduled version withdrawn before its effective date. It never applies. If Version 3 above were cancelled, Version 2 would keep applying with no end date.

Rules

  • The effective date is today or later. Published versions never change, so what applied on a past date always stays what applied.
  • Only one version can start on a given effective date.
  • A dataset has at most one Scheduled version. While it exists, no further version can be published until it becomes Current or is cancelled.
  • A dataset without a Current version is absent from ordinary read views.

Data on a given date

Ask for the version that applied on that date. In the API, effective_date=2026-02-15 returns Version 1 (Sales), and effective_date=2026-03-15 returns Version 2 (Operations). Without a date, you get the Current version. See Version selection and pagination.

Data over a period

A report for January to June 2026 spans two versions: Version 1 for January and February, Version 2 from March. Retrieve each version (version=1, version=2) and match each record to the version whose period contains its date. The effective dates are listed on the dataset’s Versions page.

Import and export

In a draft you can import a complete version from a CSV or Excel file. You map the columns to the fields and check the proposal: which records will be added, changed or deleted. The draft changes only after you confirm. Published versions can be exported as Excel, CSV or JSON, for example for use in office applications. See Import and export for details.

Records

A record holds one value per field and is found by its unique code. The fixed rules of the datatypes determine validation, equality, uniqueness and ordering.

  • Record editing is available only in an active draft.
  • Deleted records remain reviewable before publication.
  • Published version pages are read-only and retain their original schema and values.
  • Basic search covers String values using Unicode normalization and case folding.

Import and export

You import a CSV or Excel (XLSX) file into a draft. Choose the file and, where applicable, a worksheet, map the columns to fields, review the source formats and check the proposal. The import is committed in one transaction only after you confirm.

  • An import describes the complete desired version. Records missing from the file are deleted after you confirm the deletion count.
  • The dataset schema remains authoritative. Map every required and identifier field; optional fields you leave unmapped keep their values.
  • All checks run before anything is saved. An invalid value prevents the import.
  • Once a dataset has a version, you can run one import per draft, and only while the draft has no manual changes.
  • In a mapping dataset, an import updates only the target values. A hierarchy dataset is imported from the edited export of that hierarchy.

Exports

Users with export rights can download published versions as Excel, CSV or JSON, for example to use them in office applications. See Teams and access for who can export.

Teams and access

Teams represent data domains. Every dataset has exactly one owning team.

CapabilityUserUser with export or API grantOwning teamAdmin
Read published data in the appYesYesYesYes
Export and use the APIDepends on the settingYesYesYes
Maintain draftNoNoYesYes
Publish or cancelNoNoYesYes
Manage grantsNoNoDepends on the settingYes
Reassign ownershipNoNoNoYes

Exporting and using the API are one right. An API key always has the same export rights as the user who created it. A user with an export or API grant can read and export the granted datasets, but cannot maintain drafts or publish.

Who can export and use the API

Administrators choose one setting for the whole installation under Settings → Dataset access:

  • Everyone (default): every active user can export and use the API. Grants are kept but have no effect.
  • Owning team and granted users — team members can grant: administrators, owning-team members and granted users or teams can export. Team members manage grants on the dataset's Access tab.
  • Owning team and granted users — administrators only can grant: the same users can export, but only administrators manage grants.

Changes to grants, team membership or this setting apply to the next API request. Inactive and deleted users have no capabilities. A team cannot be deleted while it owns a dataset.

Audit history

Active administrators can browse Settings → Audit log. Business mutations and structural audit events commit together. Record values, secrets and arbitrary submitted metadata are excluded. Validation failures, denied actions, stale writes and rolled-back transactions do not emit success events.

API keys

Personal API keys authenticate the read-only REST API. Users create their keys under Settings → API keys. A key gives access to the datasets its owner may export; a request for any other dataset returns 404.

Enable key management with a stable secret, the pepper: 32 bytes encoded as 64 hexadecimal characters. Create it once and keep it in protected configuration so every restart uses the same pepper.

Terminal
export REFRNCR_API_KEY_PEPPER="$(openssl rand -hex 32)"
refrncr start

If you use a .env file, create it with umask 077 so only you can read it.

Protect the pepperDo not commit or log it. Changing or losing it invalidates every existing API key.
Authenticated request
curl -H 'Authorization: Bearer YOUR_API_KEY' \
  http://127.0.0.1:8000/api/v1/datasets

REST API endpoints

The Community API under /api/v1 is read-only and serves published datasets of all three types.

MethodPathResponse
GET/api/v1/datasetsDataset summaries and pagination
GET/api/v1/datasets/{dataset_key}Dataset summary and ordered fields
GET/api/v1/datasets/{dataset_key}/recordsRecords, version and pagination
GET/api/v1/datasets/{dataset_key}/records/{identifier}One record and version
GET/api/v1/datasets/{dataset_key}/lookup?source={code}Mapping dataset: the record for one source code
GET/api/v1/datasets/{dataset_key}/hierarchyHierarchy dataset: every node with its parent

Use the complete opaque identifier returned by the API, URL encoded, for record lookup.

The source-code lookup is for one value, not a general filter. A source code without a target returns 200 with empty target fields; an unknown source code returns 404. The hierarchy endpoint returns the complete structure as a flat list; the consumer builds the tree from it.

Current v1 boundarySearch, typed filters, sorting controls, writes, imports and exports are not part of REST API v1. Use the app for exports.

Swagger UI is available at /api/docs; the generated OpenAPI 3.1 document is served at /api/openapi.json.

Version selection and pagination

All data endpoints accept an optional business date, version number, or both.

ParameterMeaning
effective_date=YYYY-MM-DDLatest non-cancelled publication effective on or before the date.
version=NThe specified immutable version, including Scheduled.
BothThe version must be effective on the supplied date.
NeitherThe Current publication.

Collections accept offset (default 0) and limit (default 50, maximum 100).

Errors and conditional requests

StatusErrorMeaning
400invalid_requestInvalid parameters
401invalid_api_credentialsMissing or invalid credentials
404not_foundMissing or inaccessible resource
405method_not_allowedUnsupported method
503service_unavailableOperational failure

Successful responses include a strong ETag and publication-based Last-Modified. Prefer If-None-Match for reliable revalidation. Successful responses are private and must revalidate; errors use private, no-store.

Health and logging

  • GET /healthz reports process liveness.
  • GET /readyz reports database connectivity and migration readiness.

Every response includes X-Request-ID. Interactive terminals receive compact output; redirected output uses privacy-safe JSON lines. Supported levels are DEBUG, INFO, WARNING, ERROR and CRITICAL.

Storage and backups

Default SQLite locations:

  • Linux: $XDG_DATA_HOME/refrncr/refrncr.db or ~/.local/share/refrncr/refrncr.db.
  • macOS: ~/Library/Application Support/refrncr/refrncr.db.
  • Windows: %LOCALAPPDATA%\refrncr\refrncr.db.
Operator responsibilityRefrncr does not provide a backup service. Operators own backup scheduling, protected storage, encryption, retention and tested recovery. Stop writers and take a restorable backup before controlled upgrades.

Join the refrncr community

Ask questions, share experiences, and help shape the development of refrncr. Anyone can sign up. New accounts require administrator approval.

Join the community →