Catalog Descriptors
Machine-readable repository identity that tells catalog systems what a repository is and produces, and where the authoritative definitions live.
- Kind
- Architecture
- Domain
- Documentation & Metadata
- Applies at
.descriptor/- Status
- Stable
- Source · managed
.descriptor/README.md
01 Defines
A dedicated directory of generic, repository-owned metadata files describing a repository and the artifacts and resources it produces, with references to their sources of truth.
02 Applies when
- A cataloguing system, developer portal, inventory tool, or ownership automation needs to understand the repository.
- A repository produces resources — a website, an API, a database — that would otherwise have to be inferred from source.
- Connective metadata is needed to discover resources without understanding every underlying system.
03 Boundaries
- Descriptors never define how the repository builds, tests, deploys, or runs.
- Descriptors do not copy deployment settings, API definitions, or database configuration.
- Descriptors are not coupled to a single catalog platform.
Expected behaviour
- 01Repository-owned descriptor files live in
.descriptor/. - 02A descriptor identifies a resource and points at the file or system that defines it.
- 03The same fact is stated once; anything resolvable by reference is referenced, not repeated.
- 04Domain-specific and operational detail stays in its existing source of truth.
Behaviour#
A repository may publish a static website, expose an API, and provision a database. All three could in principle be discovered by reading source files, infrastructure definitions, and deployment configuration, but only by a consumer that understands every one of those systems and can infer how they relate.
A catalog descriptor removes the inference. It states that the resources exist and says where their definitions are. Consumers follow the reference to the source of truth rather than relying on a copy.
- 01
Read the descriptor
A catalog system reads
.descriptor/*.yamland finds a resource bykindandname - 02
Follow the reference
Paths in
specpoint at the authoritative definition, such as./openapi.yaml - 03 Read the source of truth Detail is read where it is maintained, never from a copy
Descriptors have no effect on build, test, or runtime behaviour. Removing every descriptor changes what a catalog can see, never what the repository does.
Shape of a descriptor#
Every descriptor is a small YAML document with an apiVersion, a kind, a
metadata block for identity, and a spec block for references.
apiVersion: workspace.v1
kind: Repo
metadata:
name: static-website
description: Production-ready Hugo static website starter
spec:
id: 7ec707ed-2ba5-4ba1-9a89-c70863d8a3c5
A resource descriptor points at definitions rather than restating them:
apiVersion: example.catalog.v1
kind: Endpoint
metadata:
name: public-api
spec:
definition:
path: ./openapi.yaml
deployment:
path: ./deploy/api
Connections