Skip to content

Validation Commands

Commands for validating schemas, detecting breaking changes, and suggesting version bumps.

apx lint

Validate schema files for syntax and style issues.

apx lint [path]

If path is omitted, APX detects schema directories from module_roots in apx.yaml. If path is an API ID (e.g. proto/payments/ledger/v1), APX resolves it to the local filesystem path.

Flags

Flag Shorthand Type Default Description
--format -f string auto-detected Schema format: proto, openapi, avro, jsonschema, parquet

Format-Specific Validation

Format Tool What it checks
Protocol Buffers buf lint Naming conventions, package structure, field numbering, service definitions
OpenAPI Spectral Schema structure, endpoint definitions, response formats
Avro Native Go Record structure, field type validity, required name/fields presence
JSON Schema Native Go JSON syntax, $schema URI, type, properties, required
Parquet Native Go Message-notation syntax, physical type validity, repetition levels

For protobuf, APX also runs go_package validation — warning if the go_package option doesn't match the canonical import path.

Examples

# Lint all schemas in the project
apx lint

# Lint a specific directory
apx lint internal/apis/proto/payments/ledger/v1

# Force format detection
apx lint --format proto internal/apis/

# Verbose output with details
apx lint --verbose

apx breaking

Check for breaking changes between the current schemas and a baseline.

apx breaking [path] --against <ref>

The --against flag is required and specifies the baseline to compare against.

Flags

Flag Shorthand Type Default Description
--against string (required) Git reference or path to compare against
--format -f string auto-detected Schema format

Supported Baselines

# Compare against previous commit
apx breaking --against HEAD^

# Compare against a branch
apx breaking --against origin/main

# Compare against a specific tag
apx breaking --against proto/payments/ledger/v1/v1.0.0

# Compare against a specific commit
apx breaking --against abc1234

Format-Specific Checks

Format Tool Breaking changes detected
Protocol Buffers buf breaking Field removal/renumbering, type changes, service/method removal
OpenAPI oasdiff breaking Endpoint removal, required field additions, response type changes
Avro Native Go New fields without defaults, type changes (BACKWARD/FORWARD/FULL/NONE modes)
JSON Schema Native Go Property removal, type change, required field additions
Parquet Native Go New required columns, removed columns, type/annotation changes, optional→required promotion

Examples

apx breaking --against HEAD^
apx breaking internal/apis/proto/ --against origin/main
apx breaking --format openapi --against v1.0.0

apx semver

Suggest a semantic version bump based on schema changes.

apx semver [path] --against <ref>

Flags

Flag Shorthand Type Default Description
--against string (required) Git reference to compare against
--api-id string "" API ID (e.g. proto/payments/ledger/v1)
--lifecycle string "" Lifecycle state
--format -f string auto-detected Schema format

How It Works

  1. Runs apx breaking to detect breaking changes
  2. Lists existing git tags to find the current latest version
  3. Applies versioning rules:
Change type Bump Rationale
Breaking changes Rejected Requires a new major API line (e.g. v1 → v2)
Non-breaking additive changes Minor New fields, RPCs, or endpoints
No schema changes Patch Documentation, metadata, or tooling-only changes
  1. Applies lifecycle mapping for prerelease tags:
Lifecycle Prerelease format
experimental -alpha.<n>
beta -beta.<n>
stable (none)

Examples

# Suggest based on changes since last commit
apx semver --against HEAD^
# → minor (new fields added, no breaking changes)

# With explicit API ID and lifecycle
apx semver --api-id proto/payments/ledger/v1 --lifecycle beta --against HEAD^
# → v1.1.0-beta.1

# JSON output
apx --json semver --against origin/main

apx policy check

Check schema files against organization policies.

apx policy check [path]

Validates schemas against policy rules configured in apx.yaml:

  • Forbidden proto options — rejects schemas using banned annotations (e.g. gorm.*)
  • Allowed proto plugins — ensures only approved code generation plugins are used
  • OpenAPI ruleset — applies custom Spectral rulesets
  • Avro compatibility — enforces compatibility mode (BACKWARD, FORWARD, FULL)
  • Parquet rules — enforces additive nullable-only column additions

Example

apx policy check
apx policy check internal/apis/proto/

Validation in CI

A typical CI pipeline runs all three validation commands:

- name: Validate schemas
  run: |
    apx lint
    apx breaking --against origin/main
    apx policy check

See Also