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.
Installation
--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.
pipx install --pre refrncr refrncr start
Open http://127.0.0.1:8000. Docker and PostgreSQL are not required for this quick start.
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.
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.
| Purpose | Option | Environment |
|---|---|---|
| Database URL | --database-url | REFRNCR_DATABASE_URL |
| SQLite file | --database-path | — |
| Bind address | --host | REFRNCR_HOST |
| HTTP port | --port | REFRNCR_PORT |
| Log level | --log-level | REFRNCR_LOG_LEVEL |
| Trusted proxies | --trusted-proxy | REFRNCR_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.
refrncr start --database-path ./refrncr.db
# .env in the folder where you start refrncr
REFRNCR_DATABASE_URL=postgresql+psycopg://refrncr:PASSWORD@localhost/refrncr
REFRNCR_API_KEY_PEPPER=...
refrncr start.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 dataset | Mapping dataset | Hierarchy dataset | |
|---|---|---|---|
| Represents | A list of values | A translation from source codes to target values | A tree structure |
| Example | Countries, currencies, error codes | Cost centre to reporting line | Organisation structure, regions |
| Structure | Fields and records | Source code from a reference dataset plus target fields | Root, nodes and optional fields |
| Identifier | Required, one or more fields | The source code | Optional, for leaves |
| Views | Table | Table with source and target columns | Tree and table |
| Import | Complete version from CSV or Excel | Target values from CSV or Excel | Edited export as CSV or Excel |
| Extra in the API | — | Lookup by source code | Complete 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_3and 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
1001and target valueAMS-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.
| ID | Label | Canonical form | Identifier |
|---|---|---|---|
string | String | Trimmed NFC Unicode | Yes |
integer | Integer | Ungrouped base 10 | Yes |
number | Decimal | Exact base 10 | Yes |
float | Float | Finite binary64 | No |
boolean | Boolean | true or false | Yes |
date | Date | YYYY-MM-DD | Yes |
time | Time | HH:mm:ss[.fraction] | Yes |
datetime | DateTime | Local ISO date and time | Yes |
timestamp | Timestamp | UTC timestamp ending in Z | Yes |
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.
- Create a draft. Select a published version as its baseline.
- Maintain the data. Change fields and records, or import a complete version.
- Review changes. Inspect field and record differences against the baseline.
- 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:
| Version | CC-1001 | Effective from | Applies until | Status |
|---|---|---|---|---|
| 1 | Sales | 1 Jan 2026 | 1 Mar 2026 | Expired |
| 2 | Operations | 1 Mar 2026 | 1 Jan 2027 | Current |
| 3 | Finance | 1 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.
| Capability | User | User with export or API grant | Owning team | Admin |
|---|---|---|---|---|
| Read published data in the app | Yes | Yes | Yes | Yes |
| Export and use the API | Depends on the setting | Yes | Yes | Yes |
| Maintain draft | No | No | Yes | Yes |
| Publish or cancel | No | No | Yes | Yes |
| Manage grants | No | No | Depends on the setting | Yes |
| Reassign ownership | No | No | No | Yes |
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.
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.
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.
| Method | Path | Response |
|---|---|---|
| GET | /api/v1/datasets | Dataset summaries and pagination |
| GET | /api/v1/datasets/{dataset_key} | Dataset summary and ordered fields |
| GET | /api/v1/datasets/{dataset_key}/records | Records, 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}/hierarchy | Hierarchy 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.
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.
| Parameter | Meaning |
|---|---|
effective_date=YYYY-MM-DD | Latest non-cancelled publication effective on or before the date. |
version=N | The specified immutable version, including Scheduled. |
| Both | The version must be effective on the supplied date. |
| Neither | The Current publication. |
Collections accept offset (default 0) and limit (default 50, maximum 100).
Errors and conditional requests
| Status | Error | Meaning |
|---|---|---|
| 400 | invalid_request | Invalid parameters |
| 401 | invalid_api_credentials | Missing or invalid credentials |
| 404 | not_found | Missing or inaccessible resource |
| 405 | method_not_allowed | Unsupported method |
| 503 | service_unavailable | Operational 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 /healthzreports process liveness.GET /readyzreports 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.dbor~/.local/share/refrncr/refrncr.db. - macOS:
~/Library/Application Support/refrncr/refrncr.db. - Windows:
%LOCALAPPDATA%\refrncr\refrncr.db.
Join the refrncr community
Ask questions, share experiences, and help shape the development of refrncr. Anyone can sign up. New accounts require administrator approval.