Skip to content
Componecat Docs

Entities and kinds

The catalog is made of entities. An entity is anything worth tracking: a system, a service, a shared library, a datastore, a tool, a knowledge base. Every entity has a kind that decides what it can hold, a set of fields that describe it, and an owner responsible for it.

Kinds

Section titled “Kinds”

A kind is a reusable template. It controls which features an entity has — whether it links to a repository, hosts documentation, exposes interfaces, keeps an activity log, or can have children — and which fields appear on it.

Every new organization starts with two ready-to-use kinds:

Kind Typical use
System A top-level grouping of related components.
Component A service or library, usually backed by a source repository.

More kinds ship as starter templates — add the ones you need with a click:

Kind Typical use
Resource A datastore, queue, bucket, or piece of infrastructure.
Knowledge Base A collection of documentation with no interfaces or children.
Tool An internal tool or utility.
AI Skillset A capability made available to AI agents.
Template A starting point other entities are created from.
Data Pipeline, Product Further ready-made starting points.

You can customize any kind’s display (name, icon, color, order), toggle its features, and change which fields it carries — and you can delete a kind once no entities are using it. Even the two you start with are yours to reshape.

The exception is a kind an integration writes to, such as the vendor kind used by Vendorian vendor sync. While that integration exists, the kind and the fields it uses can’t be deleted, have their key or type changed, or be removed from the kind, and the select options the integration relies on can’t be removed. Display, features, extra fields, and making a field required stay editable. The kind and field pages mark them with a Used by Vendorian sync badge (named for whichever integration uses them), and turn off the protected actions with a note saying why.

Custom kinds

Section titled “Custom kinds”

Organizations can define their own kinds — microservice, data-pipeline, golden-path, whatever fits your taxonomy — from Settings → Entity Kinds, or through the APIs. Each kind defines:

  • Display — name, description, icon, color, and sort order.
  • Features — which of repository, documentation, interfaces, activity log, and children are enabled.
  • Constraints — which kinds are allowed as children, and which interface kinds are allowed, so the catalog stays well-formed.
  • Fields — the set of fields entities of this kind carry, each optionally required.

Starter templates (like resource or data-pipeline) let an administrator bootstrap a new kind with a curated field set instead of building it from scratch.

Every organization member can browse the schema, under Schema in the navigation: Entity Kinds, Relationship Kinds, and Field Definitions show what each kind, relationship, and field means. Only administrators can create, change, or delete them; other members see the same pages read-only, and can open any field to see its type, options, and default value.

Built-in fields

Section titled “Built-in fields”

Every entity, regardless of kind, has a fixed set of fields:

Field Notes
Display name The human-readable name shown throughout the UI.
Name A URL-friendly slug; the addressable part of the entity’s reference.
Namespace An optional grouping segment in the reference.
Owner The team responsible for the entity. An organization admin can move all of a team’s entities, or a selection, to another team at once with Move to team on the team’s page.
Lifecycle Experimental, Development, Production, Deprecated, or Retired.
Description A short summary shown in cards and search results.
Tags Free-form labels for filtering and grouping.
Repository The source repository URL (on kinds that link to code).

Componecat also tracks repository metadata automatically for linked entities — the default branch, detected languages, and README content — and keeps lifecycle timestamps.

Custom fields

Section titled “Custom fields”

Beyond the built-ins, you can define your own fields and attach them to one kind, several kinds, or every kind. Fields are typed — text, number, boolean, date, URL, single- and multi-select, user or team references, labels, and structured JSON — and validated on save. Define them under Settings → Field Definitions.

A user field stores an email address. Pick a member of your workspace from the list, or type any email address to reference someone who doesn’t have a Componecat account yet.

On an entity synced from an integration, the fields the integration writes are read-only and labeled with their source; the rest stay editable. See Vendorian vendor sync.

Where a value came from

Section titled “Where a value came from”

Componecat records where each field’s current value came from, and an entity’s page marks the field with a small icon. Hover over it, tap it, or move focus to it with the keyboard to see who or what set the value, and when; press Escape to close the details. Screen readers announce the same details as the icon’s name. A manual edit names the person who made it, by their name, or by their email address if their profile has no name. An inferred value names the Catalog Intake that wrote it.

Source Meaning
Manual edit Someone changed it in the app or through the API.
Descriptor It came from the entity’s componecat.yaml.
Auto-detected Componecat read it from the repository without AI, such as a provider’s description.
Synced from an integration It mirrors an upstream record, and is read-only on a synced entity.
Inferred by AI A model suggested it during a Catalog Intake, and nobody has confirmed it.

Saving a form only changes the source of the values you actually changed. An inferred value you edit becomes a manual edit, and a later intake won’t overwrite it.

Entity references

Section titled “Entity references”

Every entity is addressable by a reference URI of the form kind://namespace/name (or kind://name when it has no namespace) — for example component://payments/payment-gateway. References are unique within an organization and are how descriptors, relationships, and API calls point at entities.

Similar entities

Section titled “Similar entities”

When your organization has an embedding model, an entity’s Overview ends with Similar entities: up to five other entities in your organization whose meaning is closest to this one’s — judged from their names, descriptions, and documentation, not from shared words or relationships. Each links to its page and shows how close a match it is as a percentage. It is a quick way to spot a near-duplicate, the other team’s version of the same thing, or a neighbor nobody has recorded as a relationship.

The section only appears when there is something to show. A newly created or edited entity is read by the embedding model in the background, so its neighbors can take a short while to appear, and an entity with nothing close enough has no section at all. In an organization without an embedding model it never appears. The same list is available from the API as similarEntities — see the search query reference.

Section titled “Related”