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

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. This file serves as the blueprint that the CLI consumes when registering assets. The 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 demonstrates a fully configured dataset entry:

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 file serves as the entry point for the command-line interface. It reads YAML manifests from paths like kcmd/entry.yaml and extracts the defined fields to register assets within the catalog system. The 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 demonstrates the complete schema implementation.
• kcmd/__main__.py handles parsing and registration of these manifests according to the project configuration in 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, 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, 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, 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.

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