Skip to content
Componecat Docs

Descriptor file reference

A componecat.yaml descriptor declares a catalog entity (or several) in a repository. Componecat ingests it on push and on scheduled scans — see Catalog as code for how discovery works. This page is the field-by-field reference.

Shape

Section titled “Shape”
apiVersion: componecat/v1
kind: component
metadata:
  name: payment-gateway
  namespace: payments
  description: Processes card transactions
  owner: team-payments
  tags: [payments, pci, critical]
spec:
  lifecycle: production
  fields:
    languages: [go, protobuf]
  interfaces:
    - kind: api
      name: Payment API
      protocol: grpc
      url: grpc://payments.internal:443
  relationships:
    - kind: depends-on
      target: resource://datastores/payments-db

Top-level keys

Section titled “Top-level keys”
Key Required Description
apiVersion Yes The descriptor schema version. Use componecat/v1.
kind Yes The entity’s kind key — for example component, system, or resource, or a custom kind your organization defines.
metadata Yes Identity and descriptive fields (below).
spec Yes Kind-specific content: lifecycle, fields, interfaces, relationships.

metadata

Section titled “metadata”
Field Required Description
name Yes URL-friendly slug; the addressable part of the entity’s reference.
namespace No Optional grouping segment in the reference (kind://namespace/name).
description Yes Short summary shown in cards and search results.
owner Yes The key of the owning team.
tags No List of free-form labels for filtering and grouping.

The displayName shown in the UI defaults from name when not set explicitly.

spec

Section titled “spec”
Field Required Description
lifecycle Yes One of experimental, development, production, deprecated, retired.
repository No The entity’s source repository URL. Discovered automatically when the descriptor is ingested from that repository.
fields No A map of custom field keys to values, validated against each field’s type.
interfaces No A list of interfaces the entity exposes.
relationships No A list of relationships to other entities.
docs No Documentation sections and external links (below).

interfaces[]

Section titled “interfaces[]”

Each interface names its kind (for example api, cli, ui, mcp, data-share, package) and a name, plus the connectivity fields for that kind — for an API, typically protocol and url. See Interfaces.

interfaces:
  - kind: api
    name: Payment API
    protocol: grpc
    url: grpc://payments.internal:443

relationships[]

Section titled “relationships[]”

Each relationship names its kind (for example depends-on) and a target — the reference URI of the other entity. If the target isn’t ingested yet, Componecat resolves the link automatically once it exists, so ordering across a push doesn’t matter.

relationships:
  - kind: depends-on
    target: resource://datastores/payments-db

docs

Section titled “docs”

docs carries two lists: sections, the entity’s documentation sections, and links, external documentation links.

docs:
  sections:
    - title: Overview
      type: overview
      content: |
        Handles card authorization and capture.
    - title: Architecture
      type: architecture
      sourcePath: docs/architecture.md
  links:
    - title: Runbook (Confluence)
      url: https://confluence.example.com/payments/runbook

Each section names a title and an optional type (overview, architecture, runbook, or a name of your own). Its content comes from one of two places:

Field Description
content Inline Markdown, authored in the descriptor itself.
sourcePath A file path or glob in a repository — the section is kept in step with those files by documentation sync.
sourceRepository Optional repository URL for a sourcePath section. Defaults to the entity’s own repository.
sourceBranch Optional branch for a sourcePath section. Defaults to the repository’s default branch.

Each link names a title and a url.

Monorepos

Section titled “Monorepos”

Place a descriptor at each relevant path in a repository (at any depth) to declare several entities from one repo. Each is ingested independently. See Catalog as code → Monorepos.

Section titled “Related”