Configuration Reference¶

The APX configuration file (apx.yaml) defines your organization's schema management settings. It controls validation policies, release behavior, tool versions, and code generation targets.

Overview¶

Every APX workspace requires an apx.yaml at the repository root. The file follows a strict schema — use apx config validate to verify correctness and apx config migrate to upgrade to newer schema versions.

Quick Start¶

# Initialize a new configuration
apx config init

# Validate an existing configuration
apx config validate

# Validate with JSON output
apx config validate --json

# Migrate to the latest schema version
apx config migrate

Schema Version¶

The current schema version is 1. The version field is required and must be set to a supported version number.

version: 1

Required Fields¶

Complete Field Reference¶

Section Details¶

import_root¶

Decouples the public Go import path from your Git hosting URL. When set, all derived Go module and import paths use this root instead of source.repo.

import_root: go.acme.dev/apis

Without import_root (default):

Go module: github.com/acme/apis/proto/payments/ledger
Go import: github.com/acme/apis/proto/payments/ledger/v1

With import_root: go.acme.dev/apis:

Go module: go.acme.dev/apis/proto/payments/ledger
Go import: go.acme.dev/apis/proto/payments/ledger/v1

The source.repo field still reflects the actual Git repository. Only the public import identity changes.

Use cases: - Vanity domain imports (go.company.dev/apis) - Migration-proof paths — change Git hosts without breaking consumer imports - Custom module registries (buf.build/gen/go/acme/apis)

Affected commands: inspect identity, inspect release, explain go-path, show, release prepare, release promote.

catalog_url¶

Points apx search, apx show, apx add, apx update, and apx upgrade at your organization's canonical catalog without passing --catalog on every command. Accepts a local file path or an https:// URL.

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

Resolution order (same as the unified catalog resolution below):

1. --catalog flag (if provided)
2. catalog_registries from apx.yaml (if configured)
3. Auto-discover from org (query GHCR for *-catalog packages)
4. catalog_url from apx.yaml
5. Local catalog/catalog.yaml

Use cases: - App repos that don't clone the canonical repo still get apx search/apx show working - CI pipelines that pin a specific catalog revision via URL - Teams on a fork pointing at the upstream catalog

See Dependency Discovery for full examples.

catalog_registries¶

Lists OCI-based catalog registries for API discovery. Each entry identifies a GHCR-hosted catalog container derived from a canonical repository. APX pulls catalog data from these containers, caches it locally, and aggregates results from multiple registries.

catalog_registries:
  - org: acme
    repo: apis            # → ghcr.io/acme/apis-catalog:latest
  - org: acme
    repo: shared-schemas  # → ghcr.io/acme/shared-schemas-catalog:latest
  - org: partner-co
    repo: public-apis     # cross-org discovery

Resolution order for catalog commands:

1. --catalog flag (if provided)
2. catalog_registries from apx.yaml (this field)
3. Auto-discover from org (query GHCR for *-catalog packages)
4. catalog_url from apx.yaml
5. Local catalog/catalog.yaml

Use cases: - Aggregate API catalogs from multiple canonical repos in a single apx search - Cross-org discovery when depending on partner APIs - Offline resilience via local cache with automatic refresh

module_roots¶

Lists the directories that contain schema modules. Each entry is a relative path from the repository root.

module_roots:
  - proto
  - openapi
  - avro
  - jsonschema
  - parquet

language_targets¶

Configures code generation for each target language. Each key is a language name with settings for plugins and tools.

language_targets:
  go:
    enabled: true
    plugins:
      - name: protoc-gen-go
        version: v1.64.0
      - name: protoc-gen-go-grpc
        version: v1.5.0
  python:
    enabled: true
    tool: grpcio-tools
    version: "1.64.0"

policy¶

Controls validation rules for schema files across all supported formats.

policy:
  forbidden_proto_options:
    - "^gorm\\."
  allowed_proto_plugins:
    - protoc-gen-go
    - protoc-gen-go-grpc
  openapi:
    spectral_ruleset: ".spectral.yaml"
  avro:
    compatibility: "BACKWARD"
  jsonschema:
    breaking_mode: "strict"
  parquet:
    allow_additive_nullable_only: true

release¶

Controls how schema versions are tagged and released.

release:
  tag_format: "{subdir}/v{version}"
  ci_only: true

The tag_format must contain {version}. The ci_only flag restricts releasing to CI environments (recommended for production use).

tools¶

Pins specific versions of external tools used by APX.

tools:
  buf:
    version: v1.66.1
  oasdiff:
    version: v1.9.6
  spectral:
    version: v6.11.0
  avrotool:
    version: "1.11.3"

execution¶

Controls where tools run.

execution:
  mode: "local"
  container_image: ""

api_sources¶

Declares remote repositories whose git tags are scanned for API releases during catalog generation. This enables first-party APIs that live in separate repositories with non-canonical directory layouts to appear in the catalog without changing their import paths.

api_sources:
  - repo: github.com/Infoblox-CTO/ngp.authz
    import_mode: preserve
    path_map:
      proto/infoblox/authz/v1: dbapiserver/pkg/pb
      proto/infoblox/licensing/v1: proto/licensing

  - repo: github.com/infobloxopen/third-party-apis-google
    import_mode: preserve
    path_map:
      proto/google/api/v1: google/api

Each entry requires repo. Optional fields include import_mode (default: preserve) and path_map which maps canonical API IDs to actual source paths in the remote repository.

Tags in the remote repository must follow the standard release pattern: <format>/<domain>/<name>/<line>/v<semver> (e.g. proto/infoblox/authz/v1/v1.0.0).

Modules discovered from API sources have origin: sourced in the catalog to distinguish them from local first-party modules and external registrations.

external_apis¶

Registers third-party APIs for inclusion in the catalog and dependency system. See External API Registration for full workflow documentation.

external_apis:
  - id: proto/google/pubsub/v1
    managed_repo: github.com/acme/apis-contrib-google
    managed_path: google/pubsub/v1
    upstream_repo: github.com/googleapis/googleapis
    upstream_path: google/pubsub/v1
    import_mode: preserve
    origin: external
    description: Google Cloud Pub/Sub API
    lifecycle: stable
    version: v1.0.0

Each entry requires id, managed_repo, managed_path, upstream_repo, and upstream_path. Optional fields include import_mode (default: preserve), origin (default: external), description, lifecycle, version, owners, and tags.

api¶

Defines the canonical identity of an API. The API ID uses a four-part format: <format>/<domain>/<name>/<line>.

api:
  id: proto/payments/ledger/v1
  format: proto
  domain: payments
  name: ledger
  line: v1
  lifecycle: beta

The line field represents the API compatibility line (v1, v2, etc.). Only breaking changes create a new line. The lifecycle field tracks the maturity state independently from the release version.

source¶

Identifies where the canonical source lives.

source:
  repo: github.com/acme/apis
  path: proto/payments/ledger/v1

The path is typically identical to the api.id and represents the directory within the canonical repository.

releases¶

Tracks the current release version for this API line.

releases:
  current: v1.0.0-beta.1

Release versions follow SemVer. Alpha/beta status is expressed in the version string (e.g. v1.0.0-alpha.1, v1.0.0-beta.1), not in the import path. This ensures consumers never need to rewrite imports between pre-release and GA.

languages¶

Derived language-specific coordinates. APX computes these automatically from the API identity and source repository.

languages:
  go:
    module: github.com/acme/apis/proto/payments/ledger
    import: github.com/acme/apis/proto/payments/ledger/v1

Go module path rules:

This follows Go's major version suffix convention: v1 modules have no suffix, v2+ modules include /vN in the module path.

Identity Inspection¶

Use apx inspect and apx explain to query the identity model:

# Show full identity for an API
apx inspect identity proto/payments/ledger/v1

# Show identity for a specific release
apx inspect release proto/payments/ledger/v1@v1.0.0-beta.1

# Explain Go path derivation rules
apx explain go-path proto/payments/ledger/v1

Example Configuration¶

A complete minimal configuration:

version: 1
org: your-org-name
repo: apis
# import_root: go.your-org-name.dev/apis   # optional: custom Go import prefix
# site_url: apis.internal.your-org-name.dev  # optional: custom domain for catalog site

module_roots:
  - proto
  - openapi
  - avro
  - jsonschema
  - parquet

language_targets:
  go:
    enabled: true
    plugins:
      - name: protoc-gen-go
        version: v1.64.0
      - name: protoc-gen-go-grpc
        version: v1.5.0

policy:
  forbidden_proto_options:
    - "^gorm\\."
  allowed_proto_plugins:
    - protoc-gen-go
    - protoc-gen-go-grpc
  openapi:
    spectral_ruleset: ".spectral.yaml"
  avro:
    compatibility: "BACKWARD"
  jsonschema:
    breaking_mode: "strict"
  parquet:
    allow_additive_nullable_only: true

release:
  tag_format: "{subdir}/v{version}"
  ci_only: true

tools:
  buf:
    version: v1.66.1
  oasdiff:
    version: v1.9.6
  spectral:
    version: v6.11.0
  avrotool:
    version: "1.11.3"

execution:
  mode: "local"
  container_image: ""

Validation¶

Run apx config validate to check your configuration against the canonical schema:

$ apx config validate
Configuration is valid

$ apx config validate --json
{
  "valid": true,
  "errors": [],
  "warnings": []
}

Validation checks include: - Required fields: version, org, repo must be present - Type checking: Each field must match the expected type (string, boolean, integer, list, map) - Enum validation: Fields with allowed values are checked (e.g., execution.mode must be local or container) - Pattern validation: release.tag_format must contain {version} - Unknown keys: Any field not in the schema is reported as an error - Deprecated fields: Fields marked as deprecated emit warnings (not errors)

Migration¶

When the schema version changes, use apx config migrate to upgrade:

$ apx config migrate
apx.yaml is already at version 1 (current). No migration needed.

Migration automatically: - Backs up the original file to apx.yaml.bak - Applies all version-to-version migration steps - Reports changes made during migration