Defining EntryLinks and Relationships Between Catalog Entries in YAML

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, 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.

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.

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.

# 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.

---
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, 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) 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.

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