Data Model Overview
Qarion organizes data governance around a set of interconnected entities. Understanding these entities and their relationships is essential for working with the API effectively, since every endpoint you call operates on one or more of these objects.
Entity Hierarchy
Organization
└── Spaces (multi-tenant workspaces)
├── Data Products (tables, views, dashboards)
│ ├── Fields (columns, schema)
│ ├── Tags (categorization)
│ ├── Lineage (upstream/downstream)
│ ├── Quality Checks → Alerts
│ └── Governance (owner, steward, custodian)
│
├── Source Systems (external platforms)
│ ├── Credentials
│ └── Roles (access policies)
│
├── Contracts (SLAs between products)
│
├── Issues (quality/data problems)
│
├── Meetings (governance reviews)
│ └── Action Items
│
└── Access Requests → Product Access
Everything in Qarion sits inside a Space, which acts as a multi-tenant workspace. Spaces contain data products, source systems, issues, meetings, and contracts — all scoped so that teams can work independently without interfering with one another. The sections below walk through each entity in detail.
Core Entities
Spaces
A Space is the foundational unit of multi-tenancy in Qarion. It isolates data, users, and configurations so that different teams or environments can operate independently within the same organization. Each space is identified by a unique slug (a URL-friendly identifier) and a human-readable name, and it contains its own set of members who are granted access.
In practice, you might create separate spaces for different environments (development, staging, production), for distinct business units (Marketing, Finance, Engineering), or for subsidiaries that need their own data catalogs. A space contains all the other entities described on this page — products, issues, meetings, contracts, and source systems — and its boundaries are strict: users cannot access resources across spaces unless they are members of both.
Data Products
A Data Product is the central entity in Qarion's data catalog. It represents a registered data asset — which could be a database table, a view, a dashboard, an API, a file export, or any other data entity your team cares about tracking. Every data product carries a name and a slug for identification, a product_type that classifies the kind of asset it represents (such as table, view, dashboard, or api), and a provider that indicates the source platform (for example, Snowflake, BigQuery, or dbt).
Beyond basic identification, each product includes a hosting_location that records where the asset physically lives (e.g., database.schema.table), a brief description for catalog listings, and a longer-form documentation field that supports full Markdown. Together, these properties make it possible for anyone in the organization to discover, understand, and evaluate a data asset without having to track down its creator.
Data products sit within a space, are linked to fields, tags, quality checks, and lineage relationships, and are governed by three distinct roles: an owner, a steward, and a custodian.
Fields
Fields represent the columns or attributes within a Data Product, capturing the schema that describes its structure. Each field records a name, a data_type (such as VARCHAR, INTEGER, or TIMESTAMP), a human-readable description of its business meaning, and flags that indicate whether the field is part of the primary key (is_primary_key) or allows null values (is_nullable).
Documenting fields at this level of detail enables column-level search across the catalog, helps consumers understand the shape of a dataset before querying it, and makes it possible to track schema evolution over time when fields are added, removed, or altered.
Tags
Tags provide a flexible way to categorize and filter Data Products across your catalog. Each tag has a name, a slug, a category that groups related tags together, and a color for visual identification in the UI.
Tags follow a many-to-many relationship with products, meaning a single tag can be applied to many products and a single product can carry many tags. Common categories include:
| Category | Examples |
|---|---|
domain | Marketing, Sales, Finance |
sensitivity | PII, Confidential, Public |
tier | Bronze, Silver, Gold |
team | Data Engineering, Analytics |
This categorization is especially useful for filtering the catalog by business domain, identifying sensitive data that requires special handling, or distinguishing between raw and curated assets using a tiered classification scheme.
Source Systems
A Source System represents a connection to an external data platform such as Snowflake, BigQuery, PostgreSQL, or dbt Cloud. It captures the platform type, platform-specific config (such as account identifiers or project names), and securely stored credentials for authentication.
Source systems serve three primary purposes in the platform. First, they enable automatic metadata synchronization — Qarion can pull schema information, column definitions, and other metadata directly from the connected warehouse. Second, they allow you to define access roles that map to real permissions in the external platform. Third, they support lineage tracing by providing the context needed to connect data products to their underlying infrastructure.
Each source system belongs to a space and can define one or more roles that users may request access to.
Roles (Source System Roles)
A Role in the context of a source system represents a specific level of access that users can request. Each role has a name (such as "Analytics Reader"), an external_role that maps to the corresponding permission in the source platform, and optionally a workflow_id that ties the role to an approval workflow.
Roles bridge the gap between Qarion's internal access governance and the permissions that actually exist in your external data infrastructure. When a user submits an access request for a particular role, the platform can route that request through the approval workflow, and upon approval, the role mapping provides the information needed to provision access in the external system.
Quality Checks
A Quality Check is an automated validation rule that monitors the health of a data product. Each check has a name, a check_type that determines the kind of validation it performs, a config object with type-specific parameters, a schedule expressed as a cron expression, and a severity level that determines how failures are prioritized.
Qarion supports five built-in check types:
| Type | What it checks |
|---|---|
freshness | Data recency (last update time) |
row_count | Volume thresholds |
uniqueness | Duplicate detection |
not_null | Null value validation |
custom_sql | Any custom SQL assertion |
When a check fails, it produces an alert that surfaces in the platform's alerts center and can trigger notifications, issue creation, or automated remediation workflows. Quality checks belong to one or more data products, and together they contribute to the product's aggregated quality score.
Alerts
An Alert is a notification generated when a Quality Check fails. It captures the severity of the failure, the current status (which can be open, acknowledged, or resolved), a message describing what went wrong, and a triggered_at timestamp recording when the alert was created.
Alerts follow a simple lifecycle. When a check fails, the alert enters the Open state, indicating it needs attention. A team member can move it to Acknowledged to signal that someone is investigating the issue. Once the underlying problem is fixed and the check passes again, the alert transitions to Resolved — either manually or automatically. Critical alerts can also be escalated into formal issues for structured tracking and resolution.
Issues
An Issue is a tracked problem or task related to data quality, governance, or operations. Issues have a title, a detailed description (which supports Markdown), a status (open, in_progress, or resolved), a priority level (low, medium, high, or critical), and an assignee who is responsible for resolving the problem.
Issues provide a structured way to manage data incidents that go beyond a simple alert. While an alert tells you that something is wrong, an issue lets you assign ownership, track progress, coordinate across teams, and maintain a history of comments and decisions. Issues belong to a space and can optionally be linked to a specific data product or to the alert that originally surfaced the problem.
Contracts
A Contract is a formal agreement between a producer (an upstream data product) and a consumer (a downstream data product) that defines service level expectations. Each contract includes a name, references to the producer and consumer products, a set of sla terms, and an optional expires_at date.
SLA terms can specify several measurable guarantees:
| Term | Description |
|---|---|
freshness_hours | Maximum data staleness |
availability_percent | Uptime guarantee |
quality_score_min | Minimum acceptable quality |
Contracts formalize the expectations that downstream teams have of their upstream data sources. When an SLA term is breached — for example, when data becomes staler than the agreed-upon threshold — the platform automatically tracks the violation, making it possible to hold producers accountable and to surface the impact of data issues across the organization.
Meetings
A Meeting represents a scheduled governance review or team sync. Each meeting has a title, a start_time and end_time, a list of attendees, notes (stored as Markdown), and a status (scheduled, completed, or cancelled).
Governance meetings are a common mechanism for data teams to review quality trends, make decisions about data standards, and align on priorities. In Qarion, meeting records serve as an audit trail — capturing who attended, what was discussed, what decisions were made, and what follow-up actions were assigned. Each meeting can also have attachments and action items linked to it.
Action Items
An Action Item is a task assigned during a meeting that needs to be completed by a specific person before a deadline. Each action item has a title describing the task, an assignee, a due_date, and a status that is either pending or completed.
Action items close the loop between governance discussions and actual follow-through. By tracking them alongside the meeting record, teams can ensure that decisions made in governance reviews translate into concrete work — and that nothing falls through the cracks.
Access Requests
An Access Request is submitted when a user wants to gain access to a data product through a specific role. The request includes a reference to the requester, the target product, the requested role, a description providing justification, and a status that tracks the request through its lifecycle.
The lifecycle of an access request typically moves through four stages. First, the user submits the request with a justification. The request then enters a pending state while it awaits approval — which may involve one or more approvers depending on the configured workflow. Once a decision is made, the request is either approved or rejected. If approved, access is provisioned in the external source system, creating a Product Access record that links the user to the product.
Product Access
A Product Access record represents an active permission grant linking a user to a data product through a specific role. It captures who has access, what product they can access, which role defines their permission level, when access was granted, an optional expires_at date, and whether the grant is_active.
Product access records make it possible to answer questions like "Who has access to this dataset?" or "What data can this user reach?" — questions that are essential for security audits, compliance reviews, and periodic access recertification. When access is no longer needed, it can be revoked by deactivating the record.
Users
A User is a person with an account on the platform. Each user is identified by their email, has a first_name and last_name for display, an is_superadmin flag indicating platform-wide administrative rights, and a list of spaces they belong to.
Users interact with Qarion through two layers of roles. Platform roles determine system-level access:
| Level | Scope | Permissions |
|---|---|---|
| Superadmin | Platform | Full access everywhere |
| Space Admin | Space | Manage space settings, members |
| Editor | Space | Create/edit products, issues |
| Viewer | Space | Read-only access |
In addition to platform roles, users can hold governance roles on individual data products:
| Role | Responsibility |
|---|---|
| Owner | Business accountability |
| Steward | Data quality and standards |
| Custodian | Technical operations |
These two role systems work independently — a user might be an Editor in a space (defining what actions they can take) while also being the Steward of a specific product (defining their governance accountability for that asset).
Entity Relationships Diagram
Next Steps
- API Reference — Work with these entities via API
- Quick Start — Make your first API call