All code blocks from the documentation - terminals, configs, schemas, workflows
Core command outputs from reference/cli.mdx
Project initialization - scans for specs and creates config
$ contractual init Scanning for contract specs... Detected specs ✔ openapi api/openapi.yaml ✔ json-schema schemas/user.schema.json Created contractual.yaml Created .contractual/ Wrote snapshots for 2 contract(s)
Spec validation - shows errors and passes
$ contractual lint Linting contracts... payments-api (openapi) ✖ [error] oas3-api-servers No servers defined api/openapi.yaml:1 ✔ user-schema (json-schema) No violations 1 contract(s) passed, 1 contract(s) have errors.
Breaking change detection - compares against snapshots
$ contractual breaking Comparing contracts against last snapshot... payments-api (openapi) ✖ [breaking] DELETE /v1/charges/{id} Endpoint removed ✔ [non-breaking] GET /v1/charges Response field `metadata` added user-schema (json-schema) ✔ No changes detected. 1 breaking change(s) found.
Interactive changeset creation with prompts
$ contractual changeset Detected changes in payments-api (openapi): ✖ [breaking] DELETE /v1/charges/{id} Endpoint removed ? Bump type for payments-api: (major) ? Summary: Remove deprecated endpoint Wrote .contractual/changesets/fuzzy-lion-dances.md
Consume changesets and bump versions
$ contractual version Reading changesets... fuzzy-lion-dances.md → payments-api major Resolved bump types: payments-api 1.4.2 → 2.0.0 (major) Snapshotting specs... ✔ .contractual/snapshots/payments-api@2.0.0.yaml Updated .contractual/versions.json Updated CHANGELOG.md Deleted 1 changeset file(s) Done. Commit these changes to complete the release.
Show current versions and pending changesets
$ contractual status Contract Versions ───────────────────────────────────────────────────── payments-api v1.4.2 → v2.0.0 (major pending) user-schema v0.9.1 ✔ up to date Pending changesets (1): fuzzy-lion-dances.md contracts: payments-api bump: major Run `contractual version` to apply these changesets.
Lint command outputs from linting/usage.mdx
Full lint run across all registered contracts
$ contractual lint Linting contracts... payments-api (openapi) ✖ [error] oas3-api-servers No servers defined api/openapi.yaml:1 ✔ user-schema (json-schema) No violations 1 contract(s) passed, 1 contract(s) have errors.
Target a specific contract with --contract flag
$ contractual lint --contract payments-api Linting payments-api... ✖ [error] oas3-api-servers No servers defined api/openapi.yaml:1 ✖ [warn] operation-tags Operation "GET /charges" has no tags api/openapi.yaml:42 2 violation(s) found (1 error, 1 warning).
Breaking command outputs from breaking/usage.mdx
Detect breaking changes across all contracts
$ contractual breaking Comparing contracts against last snapshot... payments-api (openapi) ✖ [breaking] DELETE /v1/charges/{id} Endpoint removed ✖ [breaking] GET /v1/charges Response field `currency` removed ✔ [non-breaking] GET /v1/charges Response field `metadata` added user-schema (json-schema) ✔ No changes detected. 2 breaking change(s) found across 1 contract(s).
Target specific contract for breaking check
$ contractual breaking --contract payments-api Comparing payments-api against last snapshot... ✖ [breaking] DELETE /v1/charges/{id} Endpoint removed ✖ [breaking] GET /v1/charges Response field `currency` removed ✔ [non-breaking] GET /v1/charges Response field `metadata` added 2 breaking change(s) found.
Use --base to compare against a tagged version
$ contractual breaking --base v1.2.0 Comparing contracts against snapshot v1.2.0... payments-api (openapi) ✖ [breaking] GET /v1/charges Response field `currency` removed 1 breaking change(s) found.
Changeset and version outputs from versioning/usage.mdx
Create changeset with interactive prompts
$ contractual changeset Detected changes in payments-api (openapi): ✖ [breaking] DELETE /v1/charges/{id} Endpoint removed ✔ [non-breaking] GET /v1/charges Response field `metadata` added ? Bump type for payments-api: (major) ? Summary: Remove deprecated DELETE /v1/charges/{id} endpoint and add metadata field Wrote .contractual/changesets/fuzzy-lion-dances.md
Auto-generate changeset without prompts for CI
$ contractual changeset --no-interactive
Auto-generating changeset for detected changes...
payments-api: major bump detected (breaking changes found)
Wrote .contractual/changesets/silver-hawk-runs.md Create changelog-only changeset with no spec changes
$ contractual changeset --empty ? Bump type: (patch) ? Summary: Update changelog with maintainer notes Wrote .contractual/changesets/brave-wolf-leaps.md
Consume all pending changesets and bump versions
$ contractual version Reading changesets... fuzzy-lion-dances.md → payments-api major silver-hawk-runs.md → user-schema minor Resolved bump types: payments-api 1.4.2 → 2.0.0 (major) user-schema 0.9.1 → 0.10.0 (minor) Snapshotting specs... ✔ .contractual/snapshots/payments-api@2.0.0.yaml ✔ .contractual/snapshots/user-schema@0.10.0.json Updated .contractual/versions.json Updated CHANGELOG.md Deleted 2 changeset file(s) Done. Commit these changes to complete the release.
Preview version changes without writing files
$ contractual version --dry-run [dry-run] Reading changesets... fuzzy-lion-dances.md → payments-api major silver-hawk-runs.md → user-schema minor [dry-run] Resolved bump types: payments-api 1.4.2 → 2.0.0 (major) user-schema 0.9.1 → 0.10.0 (minor) [dry-run] No files were written.
Configuration snippets from reference/configuration.mdx
Minimal config with two contracts registered
# yaml-language-server: $schema=https://contractual.dev/schema.json contracts: - name: orders-api type: openapi path: ./specs/orders.openapi.yaml - name: order-schema type: json-schema path: ./schemas/order.schema.json
Full config with custom linter, differ, and code generator
contracts: - name: orders-api type: openapi path: ./specs/orders.openapi.yaml lint: "spectral lint {spec} --format json" breaking: "oasdiff breaking {old} {new} --format json" outputs: - name: typescript-client command: "orval --input {spec} --output ./src/generated" publish: commit: true tag: true release: true
Opt out of specific checks per contract
contracts: - name: internal-config type: json-schema path: ./config/internal.schema.json lint: false # Skip linting breaking: false # Skip breaking detection
JSON Schema examples from getting-started/quickstart.mdx and recipes/
Sample order schema used in quickstart tutorial
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://example.com/order.schema.json",
"title": "Order",
"type": "object",
"required": ["id", "status", "amount"],
"properties": {
"id": { "type": "string" },
"status": { "type": "string" },
"amount": { "type": "number" }
}
} Event schema for Kafka/SNS topic
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "OrderCreated",
"description": "Published when an order is placed.",
"type": "object",
"required": ["orderId", "customerId", "totalAmount"],
"additionalProperties": false,
"properties": {
"orderId": { "type": "string" },
"customerId": { "type": "string" },
"totalAmount": { "type": "number" }
}
} Enable YAML schema validation in VS Code
{
"yaml.schemas": {
"https://contractual.dev/schema.json": "contractual.yaml"
}
} Changeset format from versioning/changeset-format.mdx
Standard changeset with bump types and summary
--- "orders-api": major "order-schema": minor --- ## orders-api Removed `internal_trace_id` field from Order response. ## order-schema Added optional `shipping_address` field.
Manually override auto-detected bump type
--- "orders-api": patch # was: major; field removed but unused --- Removed the internal `internal_trace_id` field from the Order response. This field was never documented and no external consumers reference it.
CI/CD workflow snippets from github-action/
Run lint + breaking checks on pull requests
name: Contract Governance on: pull_request: paths: - 'specs/**' - 'schemas/**' jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - uses: contractual-dev/action@v1 with: mode: pr-check github-token: ${{ secrets.GITHUB_TOKEN }}
Auto-version on merge to main
name: Release Contracts on: push: branches: [main] jobs: release: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: contractual-dev/action@v1 with: mode: release github-token: ${{ secrets.GITHUB_TOKEN }}