Skip to content

Catalog Schema

The catalog/catalog.yaml file is the organization-wide index of released API schemas. It is generated automatically by apx catalog generate (run by canonical CI on every merge) and consumed by apx search, apx show, apx add, apx update, apx upgrade, and apx catalog resolve.

Authoritative location

catalog/catalog.yaml is the single source of truth. apx catalog generate, apx release finalize, and apx release promote all read and write this same path — there is no separate root-level catalog.yaml. catalog generate rebuilds the index from the repo's release tags and then preserves the fields tags cannot express: a lifecycle that has been advanced in place (see below), plus curated tags, owners, and description.

Recorded lifecycle and tags

A module's lifecycle and first-party tags are recorded on the annotated release tag by finalize (from --lifecycle and repeatable --tag flags) and reflected in the catalog. This means:

  • A module released --lifecycle deprecated shows deprecated in the generated catalog rather than a lifecycle re-derived from its semver.
  • apx release promote <api-id> --to deprecated (or --to sunset) with no --version performs an in-place lifecycle change: it updates the module's lifecycle in catalog/catalog.yaml without minting a new version. catalog generate preserves that further-along lifecycle on subsequent runs. Commit the catalog change to publish it.

Catalog File Structure

version: 1
org: acme
repo: apis
import_root: go.acme.dev/apis    # optional: custom Go import prefix
modules:
  - id: proto/payments/ledger/v1
    format: proto
    domain: payments
    api_line: v1
    description: Payments ledger service API
    lifecycle: stable
    version: v1.2.3
    latest_stable: v1.2.3
    latest_prerelease: v1.3.0-beta.1
    path: proto/payments/ledger/v1
    tags: [payments, internal]
    owners: [payments-team]
    resource_types:
      - payments.acme.com/Ledger

Top-Level Fields

Field Type Description
version integer Catalog schema version (always 1)
org string GitHub organization name
repo string Canonical API repository name
import_root string Custom public Go import prefix (e.g. go.acme.dev/apis). Inherited from apx.yaml.
modules list List of API module entries

Module Entry Fields

Each entry in modules describes a single released API line.

Identity

Field Type Required Description
id string yes Canonical API ID: <format>/<domain>/<name>/<line>
format string yes Schema format: proto, openapi, avro, jsonschema, parquet
domain string no Business domain (e.g. payments, billing)
api_line string no API compatibility line (e.g. v1, v2)
path string yes Filesystem path in the canonical repository
description string no Human-readable description

Versions

Field Type Description
version string Current/latest version of this API line
latest_stable string Latest stable release tag (no prerelease suffix)
latest_prerelease string Latest prerelease tag (-alpha.*, -beta.*, -rc.*)

apx update uses latest_stable first, falling back to latest_prerelease, then version.

Lifecycle and Compatibility

Field Type Allowed Values Description
lifecycle string experimental, beta, stable, deprecated, sunset Maturity/support state
compatibility string none, stabilizing, full, maintenance, eol Derived compatibility signal
production_use string Human-readable production recommendation

Metadata

Field Type Description
tags list of strings Searchable tags (e.g. ["payments", "public"])
owners list of strings Team or individual owners (e.g. ["payments-team"])

Resource Types

Field Type Description
resource_types list of strings AIP-122 resource types the module declares (e.g. iam.acme.com/User)

resource_types is the index that apx catalog resolve reads to map a resource type to its serving module. It is derived, not entered by hand: during apx catalog generate, apx scans each proto module's directory for option (google.api.resource) = { type: "..." } annotations already present in the schema and records the types found. Modules with no such annotation (or non-proto formats) simply carry no resource_types. Because the index is derived from existing annotations, populating it requires no schema release and no manual entry.

External API Provenance

These fields are populated only for external and forked APIs (registered via external_apis in apx.yaml). First-party APIs leave them empty.

Field Type Allowed Values Description
origin string external, forked Classification of the API source
managed_repo string Internal repository hosting curated snapshots
upstream_repo string Original external repository URL
upstream_path string Path within the upstream repository
import_mode string preserve, rewrite Import path handling strategy

How the Catalog Is Generated

apx catalog generate (or apx catalog generate --from-tags) scans the canonical repository and builds catalog.yaml from:

  1. Git tags — tags matching <format>/<domain>/<name>/<line>/v<semver> are parsed to populate version, latest_stable, and latest_prerelease
  2. Organization config — import_root from apx.yaml is propagated into the catalog for downstream discovery
  3. External API registrations — external_apis entries in apx.yaml are merged in to add provenance fields
  4. Resource-type annotations — each proto module's directory is scanned for google.api.resource annotations to populate resource_types (see Resource Types)

The canonical CI workflow runs apx catalog generate on every merge to keep the catalog current.

# Regenerate from git tags (canonical CI)
apx catalog generate --from-tags

# Regenerate from directory scan
apx catalog generate

Configuring Remote Catalog Access

App repos and CI pipelines that don't clone the canonical repository can point at a hosted catalog via catalog_url in apx.yaml:

catalog_url: https://raw.githubusercontent.com/acme/apis/main/catalog/catalog.yaml

All five consumer commands (search, show, add, update, upgrade) check catalog_url automatically when --catalog is not provided. See Configuration Reference.

See Also