Using Aliases to Simplify Type References in Knowledge Catalog Metadata

The Knowledge Catalog mdcode TypeScript library uses a centralized 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, 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. The repository includes predefined aliases for common Dataplex and BigQuery types, but you can extend this with custom entries for project-specific resources.

# 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. When you call CatalogSnapshot.load(), the library reads 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 – 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 (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:

# 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 and 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	Central configuration where aliases are declared.
toolbox/mdcode/docs/spec.md	Explains alias usage rules and enforcement.
toolbox/mdcode/docs/plan.md	Describes how the CLI and library handle aliases during pull/push.
toolbox/mdcode/docs/concept.md	Provides the conceptual overview of type aliases.
toolbox/mdcode/src/libts/metadata.ts	Defines the metadata objects that incorporate resolved types.
toolbox/mdcode/src/libts/layouts/standard.ts & 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, 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. 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, it reads 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.

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 rather than edits across many metadata files.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}