Skip to main content

Pact Specification

Introduction​

The Pact Specification (or simply, "Specification" or "spec") is a document that governs the structure of the actual generated contracts (pact files), and also as a test suite for matching logic, to allow for interoperability between languages such as Node and Java. It is versioned to indicate breaking changes and new features introduced that previous versions do not support.

The version of the specification required to verify a pact is written into the pact file itself (under the key metadata.pactSpecification.version).

Each language implementation of Pact needs to implement the rules of this specification, and advertise which version(s) are supported, corresponding closely to which features are available. See the current supported language features for more.

Language Compatibility​

A provider using a language that can support a particular version of the Pact specification, can interoperate with consumers with all previous versions, up to and including, the same as that of the provider.

The reverse is not true. That is, for two languages to use Pact effectively, they must both be able to understand the specification version of the pact generated by the consumer.

The following compatibility matrix illustrates this point, by showing what can be tested given the version of the specification a given client language can support:

Generated pact file spec version (Client) 👉11.1234
Provider spec support 👇
1✅
1.1✅✅
2✅✅✅
3✅✅✅✅
4✅✅✅✅✅

What if My Consumer Client Language is Incompatible with my Provider Client Language?​

If you require a feature only available in a version higher than that of the Specification your provider client supports, you have several choices:

  1. Check you have the latest provider client available to your language.
  2. If you don't need a feature present in a later version of the spec, you can choose to serialise your contract in a different version. For example, if your provider supports up to v3 and your consumer supports v4 by default, you can choose to serialise a pact with version v3. Consult your language documentation for how to do this.
  3. If you need a feature available in a later version, you can verify your provider using the Provider Verifier CLI which will always support the latest version of the spec.

Client Language Support​

The following table shows the current specification compliance for each of the supported languages:

Implementationv1v1.1v2v3v4
Pact-rust✅✅
Pact-jvm0✅✅
Pact-ruby✅
Pact-js✅✅✅*
Pact-net✅✅✅*
Pact-python✅
Pact-php✅
Pact-go✅✅✅*
Pact-C++✅✅
scala (scala-pact)✅
scala (pact4s)✅✅*
swift (pact-consumer-swift)✅
swift (pact-swift)✅
  • ✅ - Implemented and actively supported
  • ✅* - Implemented in beta
  • 0 - Implemented and not actively supported

All new Pact implementations should wrap the Rust implementation using FFI calls, to allow us to roll out new features quickly and consistently across our 10+ Pact languages.

Support is appreciated if you wish to contribute in migrating a language from the Ruby to Rust core, or wish to create a new language implementation

The Specification​

Pact Specificaton Philosophy​

The Pact matching rules follow Postel's Law.

Be as strict as we reasonably can with what we send out (requests).

We should know and be able to control exactly what a consumer is sending out. Information should not be allowed to "leak" silently.

Be as loose as we reasonably can with what we accept (responses).

A provider should be able to send extra information that this particular consumer does not care about, without breaking this consumer.

When writing the matching rules, err on the side of being more strict now, because it will break fewer things to be looser later, than to get stricter later.

Note: One implications of this philosophy is that you cannot verify, using pact, that a key or a header will not be present in a response. You can only verify what is.

Migration Guides​

In order to faciliate the move to from v2 to v3 specification, in the respective client libraries, migration guides have been written to help to transition across.

 General Notes​

  • A migration between pact specifications, for existing published contracts, will trigger a rule content_that_affects_verification_results causing a contract_content_changed / contract_requiring_verification_published event type as the generated matcher rules may have changed between specifications.

v2 to v3​