# Defining EntryLinks and Relationships Between Catalog Entries in YAML

> Learn how to define EntryLinks and relationships between catalog entries in YAML. Explore the GoogleCloudPlatform/knowledge-catalog for structured metadata management.

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

---

**In GoogleCloudPlatform/knowledge-catalog, you define relationships between catalog entries using the `links` key in YAML front-matter, where each EntryLink specifies a target entry reference and optional metadata like description or attributes.**

Knowledge Catalog stores metadata as files on disk, with each dataset, table, or glossary term represented as a YAML file or Markdown front-matter. The `links` section enables you to model typed relationships between these entries without modifying the underlying data sources.

## Understanding EntryLinks in Knowledge Catalog

An **EntryLink** is a typed edge that connects a *source* entry to one or more *target* entries. According to the conceptual design in [`toolbox/mdcode/docs/concept.md`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/docs/concept.md), these links form the graph structure of your catalog alongside the entry files and side-car aspect files.

The link type must match a definition in your catalog's taxonomy (e.g., `contains`, `belongsTo`, `hasGlossaryTerm`, `references`). In the YAML representation, the `links` key sits at the top level of the entry file and maps each link type to an array of target objects.

### YAML Structure for EntryLinks

The minimum required field for each link object is `target`, which holds a fully-qualified entry reference. You can optionally include `description` or custom `attributes` to enrich the relationship metadata.

```yaml
links:
  <entryLink-type>:
    - target: <scope>.<entry-id>
      description: "Optional explanation of the relationship"
      attributes:
        customKey: customValue

```

*   **Source entry**: The file containing the `links` block.
*   **Target entry**: Identified by the format `<scope>.<entry-id>` (e.g., `bq-dataset.myProject.myDataset`).
*   **Link type**: The key under `links` that must exist in the catalog schema.

## YAML Configuration Patterns

Knowledge Catalog supports two file layouts for defining entries and their relationships, as documented in [`toolbox/mdcode/docs/spec.md`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/docs/spec.md).

### Standard Layout Implementation

In the Standard Layout, each entry resides in its own YAML file (e.g., `<entry-id>.yaml`) with side-car Markdown files for unstructured content. The `links` block appears at the top level of the YAML file.

```yaml

# tables/orders.yaml

type: bigquery-table
name: orders
displayName: Orders Table
description: Stores e-commerce order records.
location: US
parent: projects/my-project/datasets/ecommerce
ancestors:
  - projects/my-project
  - projects/my-project/datasets/ecommerce
createTime: 2023-01-15T12:00:00Z
updateTime: 2023-10-01T08:30:00Z

links:
  belongsTo:
    - target: bq-dataset.my-project.ecommerce
  hasGlossaryTerm:
    - target: kb.my-project.glossary.order_status
      description: "Links the table to the 'order_status' term in the glossary."

```

### Documents Layout Implementation

The Documents Layout places the entire entry definition, including `links`, inside the front-matter of a single Markdown file. The unstructured content (e.g., Overview) lives in the Markdown body rather than side-car files.

```markdown
---
type: kb-article
name: data-privacy-guidelines
displayName: Data Privacy Guidelines
description: Guidelines for handling personal data.
createTime: 2024-02-10T09:00:00Z
updateTime: 2024-06-20T14:45:00Z
links:
  references:
    - target: bq-dataset.my-project.privacy_audit
      description: "Underlying audit dataset referenced in the guide."
    - target: entryGroup.my-project.compliance
      description: "Compliance entry group containing related policies."
---

# Data Privacy Guidelines

*(Markdown body with the article's content)*

```

## Target Reference Syntax and Link Types

Target references use the fully-qualified format `<scope>.<entry-id>`, where `scope` values include `bq-dataset`, `entryGroup`, `kb`, or other catalog-specific namespaces.

As implemented in [`toolbox/mdcode/docs/design.md`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/docs/design.md), the abstract `readEntry` and `writeEntry` contracts operate on files containing these `links` structures. The `kcmd` CLI validates that:
1. Link types exist in the catalog taxonomy schema
2. Target references resolve to actual entries when pulling or pushing snapshots

## Bidirectional Relationships and Validation

Knowledge Catalog does **not** automatically enforce reverse links. If you require bidirectional relationships, you must manually add a complementary `links` block to the target entry file.

For example, if Table A links to Dataset B with `belongsTo`, and you want Dataset B to acknowledge Table A, you must add a `contains` link (or appropriate reverse type) in the Dataset B YAML file pointing back to Table A.

The validation logic in `kcmd` checks link type validity against the schema defined in your catalog configuration, ensuring that only taxonomy-defined relationship types are used.

## Summary

- **EntryLinks** define typed relationships between catalog entries using the `links` key in YAML front-matter or dedicated YAML files.
- **Standard Layout** uses separate YAML files with side-car Markdown, while **Documents Layout** combines metadata and content in single `.md` files.
- **Target references** follow the format `<scope>.<entry-id>` (e.g., `bq-dataset.my-project.ecommerce`).
- **Bidirectional links** require manual definition in both source and target entry files; the system does not auto-generate reverse edges.
- **Validation** occurs via the `kcmd` CLI, which verifies link types against the catalog taxonomy and resolves target references during snapshot operations.

## Frequently Asked Questions

### What is the difference between Standard Layout and Documents Layout?

Standard Layout stores entry metadata in dedicated YAML files (e.g., [`tables/orders.yaml`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/tables/orders.yaml)) with separate Markdown files for unstructured content, while Documents Layout places all metadata, including `links`, in the front-matter of a single Markdown file with the content in the body. Choose Standard Layout for structured data assets and Documents Layout for knowledge base articles or documentation-heavy entries.

### How do I reference a target entry in an EntryLink?

Use the fully-qualified reference format `<scope>.<entry-id>`, such as `bq-dataset.my-project.myDataset` for BigQuery datasets or `kb.my-project.glossary.term` for knowledge base terms. The scope identifies the entry type namespace, and the entry ID uniquely identifies the specific resource within that scope.

### Does Knowledge Catalog automatically create reverse links?

No, the catalog does not automatically create reverse links. If you need bidirectional relationships (e.g., a table that `belongsTo` a dataset and a dataset that `contains` the table), you must manually define the complementary `links` block in both entry files. This explicit approach prevents unintended side effects and keeps relationship definitions transparent.

### How does the kcmd CLI validate EntryLinks?

The `kcmd` CLI validates EntryLinks during snapshot operations (pull or push) by verifying that each link type exists in the catalog's taxonomy schema and that all target references resolve to actual entries in the catalog. Validation errors occur if you use undefined link types or reference non-existent target entries.