---
title: "Table and Column Metadata References"
slug: "table-and-column-metadata-references"
updated: 2025-08-22T21:38:38Z
published: 2025-08-22T21:38:38Z
canonical: "docs.validatar.com/table-and-column-metadata-references"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.validatar.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Table and Column Metadata References

## Overview

Metadata Reference Custom Fields allow you to create structured links between objects in your Validatar Catalog and Projects. Unlike free-text fields, these fields reference existing metadata objects, enabling richer documentation, relationship tracking, and automation across your data landscape.

Two types of Metadata Reference Custom Fields are available:

- **Table Metadata Reference** – references to tables in your Catalog.
- **Column Metadata Reference** – references to columns in your Catalog.

You can add either type of Metadata Reference at **any level** within Validatar, including:

- **Catalog**: Data Sources, Schemas, Tables, Columns
- **Projects**: Projects, Tests, Jobs, Labels

This flexibility allows you to model keys, dependencies, and other relationships directly within your metadata.

---

## Creating a Metadata Reference Field

When creating a Metadata Reference field, you configure the following:

### 1. Basic Details

- **Name** – The display name of the field (e.g., *Business Keys*, *Foreign Key*, *Source Tables*).
- **Reference Key** – The unique key to identify the field internally.
- **Description** *(optional)* – Additional context about the field.

### 2. Scope Limitation

Control which metadata objects can be selected by limiting the reference to a level of your choosing:

- **Any Data Source** – Allow referencing any object across all data sources.
- **Same Data Source** – Restrict selection to objects within the same data source.
- **Same Schema** – Restrict selection to objects within the same schema.
- **Same Table** – Restrict selection to objects within the same table.

This ensures references are meaningful and appropriately scoped.

### 3. Value Cardinality

Decide whether the field accepts **a single value** or **multiple values**:

- **Single Value** – One reference per field (e.g., a foreign key column mapping to exactly one column).
- **Multiple Values** – Many references per field (e.g., business keys spanning multiple columns).

---

## Examples

### Example 1: Business Keys

- **Type**: Column Metadata Reference
- **Level**: Table
- **Scope**: Same Table
- **Cardinality**: Multiple Values

Use this to capture the business key columns of a table, such as `AccountID` and `ClientID`.

---

### Example 2: Foreign Key

- **Type**: Column Metadata Reference
- **Level**: Column
- **Scope**: Same Data Source
- **Cardinality**: Single Value

Use this to document a foreign key relationship from a column in one table to a column in another table within the same data source.

---

### Example 3: Source Tables

- **Type**: Table Metadata Reference
- **Level**: Table
- **Scope**: Unlimited
- **Cardinality**: Multiple Values

Use this to document a table’s original sources, potentially spanning multiple data sources.

---

## Using Metadata Reference Fields

Once created, Metadata Reference Custom Fields appear alongside your other custom fields in the Catalog and Projects. When editing an object (e.g., a table or column), you can now select actual metadata objects rather than typing free text.

This enables:

- Clearer documentation of keys and relationships.
- Automation opportunities for testing and templating.
- Consistent references across Catalog and Project contexts.

For example:

- At the **table level**, you might document business keys (`AccountID`, `ClientID`).
- At the **column level**, you might document a foreign key relationship (`DimAccount.ClientID → RawAccount.ClientID`).
- At the **table level**, you might specify source tables that feed into a transformed table.

---

## Benefits

- **Consistency** – Reference existing objects instead of manually retyping names.
- **Automation** – Drive dynamic templates tests off metadata references.
- **Flexibility** – Apply to Catalog or Project objects at any level.

---