# Understanding Human and Agent-Friendly Metadata Representations in kcmd

> Discover how kcmd uses dual-layer metadata in YAML and Markdown for human and agent readability. Learn to create structured, editable catalog data.

- Repository: [Google Cloud Platform/knowledge-catalog](https://github.com/GoogleCloudPlatform/knowledge-catalog)
- Tags: deep-dive
- Published: 2026-07-15

---

**The kcmd library stores catalog metadata as YAML entry files for structured machine data and Markdown side-car files for human documentation, creating a dual-layer representation that remains readable and editable by both developers and automated agents.**

The kcmd library serves as the core engine for Google's *Metadata as Code* tooling within the [GoogleCloudPlatform/knowledge-catalog](https://github.com/GoogleCloudPlatform/knowledge-catalog) repository. It implements **human and agent-friendly metadata representations** that bridge the gap between human-readable documentation and machine-parseable structured data. This approach stores catalog information as plain-text source files that support both manual editing in standard IDEs and automated processing by CI/CD pipelines.

## The Dual-Layer Representation Model

kcmd utilizes a dual-layer architecture that separates structured metadata from narrative documentation while maintaining their relationship through file naming conventions.

### YAML Entry Files for Structured Metadata

Each catalog entry is stored as a `<entry-id>.yaml` file containing structured metadata such as type definitions, resource identifiers, schemas, and contact information. According to the source code in [`toolbox/mdcode/README.md`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/README.md), these YAML files provide a machine-friendly format that can be parsed programmatically without special tooling, making them ideal for automated agents that need to load or modify catalog data. The directory layout mirrors the resource hierarchy, placing entries like [`catalog/prod-data.ecommerce/products.yaml`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/catalog/prod-data.ecommerce/products.yaml) in paths that reflect their logical organization.

### Markdown Side-Car Files for Human Documentation

Human-focused documentation—including overviews, descriptions, and custom aspects—is stored in `<entry-id>.<aspect>.md` files alongside their corresponding YAML entries. As documented in [`toolbox/mdcode/README.md`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/README.md), these Markdown files are instantly viewable in editors and web renderers, while agents can still extract raw text or front-matter metadata programmatically. For example, [`catalog/prod-data.ecommerce/products.overview.md`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/catalog/prod-data.ecommerce/products.overview.md) provides narrative context for the structured data in the companion YAML file.

## Programmatic Access to Metadata Representations

The TypeScript implementation in `toolbox/mdcode/src/libts/*` provides classes for interacting with these dual-layer representations.

```typescript
import * as kcmd from 'kcmd';

// Load a snapshot from disk (YAML + Markdown files)
const snapshot = await kcmd.CatalogSnapshot.fromPath('/path/to/root');

// Read a specific entry (YAML)
const entry = snapshot.entries.get('products');   // kcmd.Entry instance
console.log(entry.id, entry.type, entry.resource.displayName);

// Access the human-readable side-car (Markdown)
const overview = await entry.readAspect('overview'); // returns markdown string
console.log(overview);

```

The `CatalogSnapshot.fromPath()` method loads the entire catalog structure from disk, parsing both YAML entry files and their Markdown side-cars. The `Entry` class exposes methods like `readAspect()` to retrieve specific Markdown documentation while maintaining type-safe access to the structured YAML data.

## CLI Workflow for Managing Metadata

The kcmd CLI provides human-friendly commands for initializing and synchronizing these metadata representations.

```bash

# Initialize a new catalog entry from BigQuery

kcmd init --bigquery-dataset myproj.sales_data

# Sync YAML/Markdown from the service

kcmd pull

# Show local modifications

kcmd status

# Upload changes

kcmd push

```

These commands maintain the dual-layer representation by automatically generating both the YAML structure files and template Markdown documentation when creating new entries.

## File Structure and Specification

The implementation details are documented across several key files in the repository:

- **[`toolbox/mdcode/README.md`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/README.md)**: Describes the YAML + Markdown format and hierarchical directory layout
- **`toolbox/mdcode/src/libts/*`**: Contains the TypeScript implementation of `CatalogSnapshot`, `Entry`, and aspect handling
- **[`toolbox/mdcode/docs/concept.md`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/docs/concept.md)**: Explains the design rationale for human- and agent-friendly artifacts
- **[`toolbox/mdcode/docs/spec.md`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/docs/spec.md)**: Provides the formal specification of file structures and naming conventions

## Summary

- **kcmd** implements a dual-layer representation using YAML for structured metadata and Markdown for human documentation.
- **YAML entry files** (`<entry-id>.yaml`) store machine-parseable catalog data including types, resources, and schemas.
- **Markdown side-cars** (`<entry-id>.<aspect>.md`) provide human-readable documentation alongside structured entries.
- The **TypeScript API** exposes `CatalogSnapshot.fromPath()` and `entry.readAspect()` for programmatic access to both layers.
- The **directory hierarchy** mirrors resource organization, enhancing discoverability for both users and automated agents.

## Frequently Asked Questions

### What makes kcmd metadata representations "agent-friendly"?

The YAML entry files use standard syntax that can be parsed by any YAML library without proprietary tooling, allowing automated agents to read and modify catalog data using standard programming interfaces. The consistent file naming conventions and hierarchical directory structure enable agents to discover related metadata through filesystem traversal.

### How does kcmd keep human documentation synchronized with structured data?

kcmd stores Markdown side-car files using the `<entry-id>.<aspect>.md` naming convention alongside their companion YAML files, creating an implicit relationship through filesystem proximity. When loading a catalog entry via `snapshot.entries.get()`, the `Entry` instance maintains references to both the structured YAML data and available Markdown aspects, which can be retrieved using `entry.readAspect()`.

### Can I edit kcmd metadata files manually, or must I use the API?

You can edit both YAML entry files and Markdown side-cars manually using standard text editors, as both formats are plain-text and human-readable. The `kcmd status` and `kcmd push` CLI commands detect manual modifications and synchronize them with the central service, supporting git-based workflows where humans edit files directly while agents process them programmatically.

### What is the relationship between kcmd and the Metadata as Code concept?

kcmd is the core implementation library for the Metadata as Code tooling in the GoogleCloudPlatform/knowledge-catalog repository. It treats catalog metadata as source code artifacts stored in version control, applying software engineering practices—such as code review, linting, and CI/CD automation—to data governance through its dual-layer YAML and Markdown representation.