# kcmd Entry YAML File Format: Complete Schema Guide for Knowledge Catalog

> Master the kcmd entry YAML file format with our comprehensive schema guide. Learn required and optional fields for defining knowledge catalog assets effectively.

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

---

**The kcmd entry YAML file uses a structured manifest schema with required fields for `id`, `name`, `description`, `type`, `source`, and `access`, plus optional fields for `version` and `schema` to define knowledge catalog assets.**

The GoogleCloudPlatform/knowledge-catalog repository provides the `kcmd` command-line tool as part of the Open Knowledge Framework (okf). Understanding the entry YAML file format is essential for correctly defining datasets, models, and pipelines that the CLI registers in the knowledge catalog system.

## Location and Purpose of Entry YAML Files

In the repository structure, the canonical example resides at [`kcmd/entry.yaml`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/kcmd/entry.yaml). This file serves as the blueprint that the CLI consumes when registering assets. The [`kcmd/__main__.py`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/kcmd/__main__.py) module handles the parsing logic, reading YAML manifests from specified paths and validating their structure before ingestion.

## Schema Structure and Required Fields

The entry YAML schema requires specific top-level keys to define the asset completely.

### Core Identification Fields

- **id**: A unique identifier for the entry, typically a UUID or URL-safe slug.
- **name**: Human-readable title of the data asset.
- **description**: Concise explanation of the asset’s purpose or content.
- **type**: The category of the asset, such as `dataset`, `model`, or `pipeline`.

### Source and Access Control

- **source**: An object containing the origin details with sub-fields:
  - `url`: Location of the source data (e.g., `gs://` URIs for Cloud Storage).
  - `format`: File format identifier such as `CSV`, `Parquet`, or `JSON`.
- **access**: Access control specifications, which may include `public` boolean flags, `restricted` markers, or IAM role bindings.

### Optional Metadata and Versioning

- **metadata**: Arbitrary key-value pairs for additional information, including `owner`, `created_at`, and `tags` arrays.
- **version**: Semantic version string (e.g., `1.0.0`) for tracking asset updates.
- **schema**: JSON-schema or protobuf definition object that validates the asset’s structure.

## Complete Entry YAML Example

The following example from [`kcmd/entry.yaml`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/kcmd/entry.yaml) demonstrates a fully configured dataset entry:

```yaml
id: "weather-forecast-2024"
name: "2024 Weather Forecast Dataset"
description: "Daily forecast data for the continental United States."
type: "dataset"
source:
  url: "gs://weather-data/2024/forecast.parquet"
  format: "Parquet"
metadata:
  owner: "climate-team@example.com"
  created_at: "2024-01-15"
  tags:
    - "climate"
    - "forecast"
    - "public"
access:
  public: true
version: "1.0.0"

```

## How kcmd Parses Entry YAML Files

The [`kcmd/__main__.py`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/kcmd/__main__.py) file serves as the entry point for the command-line interface. It reads YAML manifests from paths like [`kcmd/entry.yaml`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/kcmd/entry.yaml) and extracts the defined fields to register assets within the catalog system. The [`okf/pyproject.toml`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/pyproject.toml) defines `kcmd` as a console script, linking the CLI command to the Python module’s execution logic and establishing the tool’s integration with the broader Open Knowledge Framework.

## Summary

- The entry YAML file requires `id`, `name`, `description`, `type`, `source`, and `access` fields to define catalog assets.
- Optional fields include `version` and `schema` for advanced validation and tracking.
- The example file at [`kcmd/entry.yaml`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/kcmd/entry.yaml) demonstrates the complete schema implementation.
- [`kcmd/__main__.py`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/kcmd/__main__.py) handles parsing and registration of these manifests according to the project configuration in [`okf/pyproject.toml`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/pyproject.toml).

## Frequently Asked Questions

### What is the required filename for kcmd entry files?

While the repository provides a canonical example at [`kcmd/entry.yaml`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/kcmd/entry.yaml), the tool accepts any filename passed as a command-line argument. The file must conform to the schema structure with the required top-level keys.

### How does kcmd validate the entry YAML schema?

According to the implementation in [`kcmd/__main__.py`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/kcmd/__main__.py), the CLI parses the YAML and checks for the presence of required fields such as `id`, `name`, and `type`. It validates that the `source` object contains valid `url` and `format` strings before attempting to register the asset in the catalog.

### What are the supported values for the type field?

The `type` field accepts string values such as `dataset`, `model`, or `pipeline` to categorize the asset within the knowledge catalog system, though the exact validation depends on the specific version of the okf framework.

### Where is the kcmd CLI entry point defined?

The console script entry point is declared in [`okf/pyproject.toml`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/pyproject.toml), which maps the `kcmd` command to the Python module. This configuration file establishes the tool’s dependencies and entry point references to [`kcmd/__main__.py`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/kcmd/__main__.py).