Descriptor file reference

A componecat.yaml descriptor declares one or more catalog entities 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

apiVersion: componecat/v1
kind: component
metadata:
  name: payment-gateway
  namespace: payments
  description: Processes card transactions
  owner: team-payments
  lifecycle: production
  tags: [payments, pci, critical]
spec:
  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

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: fields, interfaces, relationships, docs.

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 owning team, by its id or its name. A name is matched case-insensitively, so owner: Team Payments and owner: team payments name the same team.
lifecycle	No	One of experimental, development, production, deprecated, retired. A new entity defaults to experimental when it’s omitted.
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

Field	Required	Description
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[]

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[]

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.

Field	Required	Description
kind	Yes	The relationship kind key.
target	Yes	The reference URI of the target entity.
description	No	A short note about the relationship.
attributes	No	A map of relationship attributes — values that describe the edge itself.

relationships:
  - kind: depends-on
    target: resource://datastores/payments-db
    attributes:
      protocol: postgres
      sla: 99.9
      notes: Read replica only

Attribute keys start with a letter and contain only letters, digits, - and _, with at most 50 per relationship. Values can be scalars, lists, or nested maps. When the relationship kind defines an attribute schema, the attributes are validated against it: required attributes must be present, undefined ones are rejected, and number and boolean attributes accept YAML scalars such as 99.9 or true. Attributes that fail validation produce a sync warning naming the attribute, and that sync leaves the entity’s relationships of that kind unchanged.

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.

Multiple entities in one file

Separate documents with --- to declare several entities in one file. Each document has the full shape above and declares one entity:

apiVersion: componecat/v1
kind: component
metadata:
  name: payment-gateway
  owner: team-payments
  description: Processes card transactions
spec: {}
---
apiVersion: componecat/v1
kind: resource
metadata:
  name: payments-db
  namespace: datastores
  owner: team-payments
  description: Payment records
spec: {}

Each document is ingested on its own, so a mistake in one, such as an owner that matches no team, doesn’t stop the others. The exception is a file that can’t be read as YAML: broken syntax, or a value of the wrong shape like a list where metadata belongs, means none of the file is ingested. Two documents can’t declare the same entity (the later one fails), and empty documents, such as a trailing ---, are ignored.

See Catalog as code → Removing an entity from a file for what happens when a document is deleted.

Monorepos

You can also place a descriptor at each relevant path in a repository (at any depth). Each file is ingested independently. See Catalog as code → Monorepos.

Related

• Catalog as code
• Entities and kinds