Contract Reference (v2.0)¶
A Pacto contract is one YAML file, pacto.yaml, that says what a service is and
what it needs to run: its interfaces, dependencies, configuration, capabilities
and readiness. This section is the field-by-field reference. The smallest valid
contract is four lines:
The fields are split across contract sections, configuration and policy, dependencies and state and readiness. The rules are in validation layers, overrides and change classification. This page covers the bundle layout all of them assume.
Each interfaces, configurations and policies entry points at a schema you already have — an OpenAPI document, an AsyncAPI event definition, a gRPC service descriptor, a JSON Schema. Every referenced file must parse as JSON or YAML; see interface types.
What the contract states, and what it deliberately leaves to the platform, is in the model.
The canonical JSON Schema is
schema/pacto-v2.0.schema.json.
It is the single tracked schema and applies to every contract, which must declare pactoVersion: "2.0".
Bundle structure¶
A Pacto bundle is a self-contained directory (or OCI artifact) with the following layout:
/
├── pacto.yaml
├── interfaces/ ← optional
│ ├── openapi.yaml
│ ├── service.yaml
│ └── events.yaml
├── configuration/ ← optional
│ └── schema.json
├── policy/ ← optional
│ └── schema.json
├── docs/ ← optional
│ ├── README.md
│ ├── architecture.md
│ ├── runbook.md
│ └── integration.md
└── sbom/ ← optional
└── sbom.spdx.json
Only pacto.yaml is required. All other directories are optional — include them when your contract references files in them. Validation checks that every file referenced by pacto.yaml exists within the bundle.
When you run pacto push, the bundle is packaged as an OCI artifact — versioned, content-addressed and distributable through any OCI registry. This is how contracts travel between teams, services and environments.
docs/ — Optional documentation¶
Anything here is informational metadata — it travels with the contract but has no effect on contract semantics, validation or diff classification.
What documentation could include:
- Service overview — what the service does, its purpose within the platform
- Architecture notes — internal design, data flow, key dependencies
- Operational runbooks — incident response, scaling procedures, known failure modes
- Integration guides — how consumers should interact with the service's interfaces
sbom/ — Optional Software Bill of Materials¶
Like docs/, anything here is informational metadata — it travels with the contract but has no effect on contract semantics or validation.
Unlike docs/, SBOM files are included in diff output. When both the old and new bundles contain an SBOM, pacto diff reports package-level changes (added, removed, version, license or supplier modified). These changes are informational only — they never affect the overall diff classification.
Supported formats:
| Format | File extension | Spec version |
|---|---|---|
| SPDX | .spdx.json |
2.3 |
| CycloneDX | .cdx.json |
1.5 |
Pacto auto-detects the format by file extension. Place one or more SBOM files directly in the sbom/ directory (subdirectories are not scanned).
Generating an SBOM:
Generate with any standard tool (Syft, Trivy, cdxgen) writing SPDX/CycloneDX JSON into sbom/.
Minimal contract¶
Only pactoVersion and service are required, as in the four-line example at the top of this page. All other sections — workload, state, interfaces, configurations, policies, dependencies, capabilities, readiness, metadata and extensions — are optional. A minimal contract is useful for lightweight dependency declarations, shared libraries or contracts where runtime semantics are managed externally.