# Using Aliases to Simplify Type References in Knowledge Catalog Metadata

> Simplify Knowledge Catalog metadata type references with aliases. Learn how mdcode maps short aliases to full type names for consistent metadata management.

- Repository: [Google Cloud Platform/knowledge-catalog](https://github.com/GoogleCloudPlatform/knowledge-catalog)
- Tags: how-to-guide
- Published: 2026-07-14

---

**The Knowledge Catalog `mdcode` TypeScript library uses a centralized [`catalog.yaml`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/catalog.yaml) configuration file to map short aliases (such as `MyDataset`) to fully-qualified type names (like `dataplex.v1.EntryGroup.Entry`), automatically resolving these references during metadata read and write operations while enforcing strict consistency across all files.**

The Knowledge Catalog metadata model requires verbose, fully-qualified type identifiers such as `dataplex.v1.EntryGroup.Entry` and `bigquery.v2.Table`. Repeating these long strings across metadata files creates visual clutter and increases transcription error risk. The GoogleCloudPlatform/knowledge-catalog repository solves this through a **type alias** system defined in [`toolbox/mdcode/catalog.yaml`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/catalog.yaml), which the `mdcode` library automatically resolves when loading data via the `CatalogSnapshot` class.

## Configuring Type Aliases in catalog.yaml

Aliases are optional mappings declared under the top-level `aliases` key in [`toolbox/mdcode/catalog.yaml`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/catalog.yaml). The repository includes predefined aliases for common Dataplex and BigQuery types, but you can extend this with custom entries for project-specific resources.

```yaml

# toolbox/mdcode/catalog.yaml

aliases:
  # Custom alias for a Dataplex entry type

  MyDataset: dataplex.v1.EntryGroup.Entry
  # Built-in alias (already provided) for BigQuery table

  Table: bigquery.v2.Table

```

## How the mdcode Library Resolves Aliases

The resolution process is handled by the `CatalogSnapshot` class in [`toolbox/mdcode/src/libts/metadata.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/src/libts/metadata.ts). When you call `CatalogSnapshot.load()`, the library reads [`catalog.yaml`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/catalog.yaml), constructs an internal map of alias strings to fully-qualified types, and substitutes short names whenever it encounters them in metadata files.

```typescript
// TypeScript – reading an entry with the alias automatically resolved
import { CatalogSnapshot } from '@google/cloud/knowledge-catalog/mdcode';

const snapshot = await CatalogSnapshot.load('path/to/snapshot');
const entry = await snapshot.readEntry('my-dataset');
// entry.type is now the full type string: "dataplex.v1.EntryGroup.Entry"

```

## Validation and Consistency Enforcement

The CLI enforces that aliases are used consistently across all metadata files. According to [`toolbox/mdcode/docs/spec.md`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/docs/spec.md) (specifically around line 48), validation fails if a metadata file mixes an alias with its corresponding fully-qualified name. This prevents a single type from being referenced using two different identifiers, ensuring a single source of truth.

## Practical Metadata Example

When defining entries, you can use the alias in place of the full type string:

```yaml

# sample entry metadata (standard layout)

id: projects/my-proj/locations/us/entryGroups/dataset/entries/my-dataset
type: MyDataset          # ← uses the alias instead of the full name

resource:
  displayName: My Dataset
  description: Example dataset

```

The layout implementations in [`toolbox/mdcode/src/libts/layouts/standard.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/src/libts/layouts/standard.ts) and [`documents.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/documents.ts) handle the translation between the concise alias in your YAML files and the full type names required by the Catalog service.

## Key Source Files for Alias Management

The alias system spans configuration, documentation, and implementation layers:

| File | Role |
|------|------|
| [`toolbox/mdcode/catalog.yaml`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/catalog.yaml) | Central configuration where aliases are declared. |
| [`toolbox/mdcode/docs/spec.md`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/docs/spec.md) | Explains alias usage rules and enforcement. |
| [`toolbox/mdcode/docs/plan.md`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/docs/plan.md) | Describes how the CLI and library handle aliases during pull/push. |
| [`toolbox/mdcode/docs/concept.md`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/docs/concept.md) | Provides the conceptual overview of type aliases. |
| [`toolbox/mdcode/src/libts/metadata.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/src/libts/metadata.ts) | Defines the metadata objects that incorporate resolved types. |
| [`toolbox/mdcode/src/libts/layouts/standard.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/src/libts/layouts/standard.ts) & [`documents.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/documents.ts) | Layout implementations that read/write metadata with alias support. |

## Summary

- **Type aliases** are defined under the `aliases` key in [`toolbox/mdcode/catalog.yaml`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/catalog.yaml), supporting both built-in and custom mappings.
- The `CatalogSnapshot` class automatically resolves aliases to fully-qualified names when reading metadata, ensuring the Catalog service receives correct type identifiers.
- Validation enforces **consistent usage**, failing if a file mixes an alias with its fully-qualified equivalent.
- Using aliases improves readability, reduces copy-paste errors, and simplifies bulk type renaming to a single-line change in the configuration file.

## Frequently Asked Questions

### Where are type aliases defined in the Knowledge Catalog repository?

Aliases are defined in the top-level `aliases` key within [`toolbox/mdcode/catalog.yaml`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/catalog.yaml). This file serves as the central configuration for the `mdcode` library, and you can add custom aliases alongside the built-in Dataplex and BigQuery mappings.

### How does the mdcode library resolve alias references?

When `CatalogSnapshot.load()` is called from [`toolbox/mdcode/src/libts/metadata.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/src/libts/metadata.ts), it reads [`catalog.yaml`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/catalog.yaml) and constructs an internal mapping of alias strings to fully-qualified type names. This resolution happens automatically during metadata read and write operations, requiring no manual intervention.

### Can I use both aliases and fully-qualified names in the same metadata file?

No. The CLI enforces consistency—validation will fail if a metadata file mixes an alias with its corresponding fully-qualified name for the same type. This ensures a single source of truth across your snapshot, as documented in [`toolbox/mdcode/docs/spec.md`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/docs/spec.md).

### What are the benefits of using aliases for Knowledge Catalog types?

Aliases improve readability by replacing verbose identifiers like `dataplex.v1.EntryGroup.Entry` with short names like `MyDataset`. They reduce copy-paste errors and simplify bulk type renaming to a one-line change in [`catalog.yaml`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/catalog.yaml) rather than edits across many metadata files.