Skip to main content

Features

Here you can find the supported features and compatibility checks PactFlow applies when comparing consumer contracts (pact files) against an OpenAPI document.

Testing

Key

  • Y - Fully supported.
  • N - No support. Either the feature is not supported, or is ignored for the purposes of the checks
  • P - Partial support (see description for caveats).

Use cases

FeatureSupportedDescriptionExample
Negative scenario testingYAllow expectations for non-successful responses (e.g. 4xx, 5xx responses).Example
Inheritance and PolymorphismYInheritance is supported via the use of the discriminator keyword.Example
Content Negotiation (media types)YUse of accept header to differentiate response, or to use as a versioning strategy. Fully complies with ​RFC 9110: HTTP Semantics §12. It supports:
  • multiple Accept header values
  • parameters (;key=value)
  • interpretation and calculation of weightings (quality values)
  • resolves media-ranges (e.g. type/* or */*)
  • Order the acceptable media types by their weighting and order (no weighting specified = 1, max of 1, min of .001 and 0 = not-acceptable)
  • resolves ambiguous types via content-type hierarchy e.g. application/specific+json is a narrower type of application/json​
Examples:
Vendor specific content typesYAllows organisations to use custom (vendor) created content types. See content negotiation above for more.

OpenAPI Support

Open API Specification Versions

Spec VersionSupportedDescription
1.xNSwagger Specification v1.2
2.0Y​OpenAPI Specification v2.0
3.0.xY​OpenAPI Specification v3.0.3
3.1.xY​OpenAPI Specification v3.1.0

Document Format

FormatSupported
YAMLY
JSONY

Resource Types

FeatureSupportedDescription
HTTPY
WebhooksNReverses the direction of the check, and doesn’t make sense (Pact can’t describe a consumer expecting a provider call)

Document Schema

Full JSON Schema 2020-12 support, including resolving references ($ref)

FeatureSupportedDescriptionExample
Server ObjectNThe servers are not used in request matching. See Issue #28 for background. Comparison of Pact interactions to OAS endpoints does not consider any basePath in its comparison. In OAS 3 (and also 2), all API endpoints are considered to be relative to the base URL. For example, assuming the base URL of https://api.example.com/v1, the /users endpoint refers to https://api.example.com/v1/users. Our comparison does not consider the impact of basePath as there may be multiple servers with different context paths and there is no clear way to resolve this ambiguity. In this example, a pact interaction with path /v1/users/ will not match an OAS that only has /users/ in its resource path.Example
Security FilteringNIgnored
InfoNIgnored
ContactNIgnored
LicenseNIgnored
External DocumentationNIgnored
Security SchemePSee below for detail. Supports all valid values, only validates only: apiKey
Relative ReferencesY
CallbacksNNot supported
Parameter stylesPSee also https://swagger.io/docs/specification/serialization/.

Missing parameters will cause a validation warning but not fail the checks

We can’t currently compare non-primitive query string values to the OAS, because Pact does not encode the style of encoding. This means we can’t reliably differentiate the cases where an object or array is encoded. We can check primitive values match the schema.

Where a pact interaction does not satisfy a parameter constraint, you will see a message such as: Path or method not defined in spec file: GET /path/style/simple/single/value/0 (the 0 here does not match the schema, which specifies the value must be > 0)
Example
Path parametersPUnderstands primitive parameters, and is able to apply schema validation to primitive data types e.g. restricting values between 1-10 for integers. Does not support array or objects.Example
Query parametersPQuery parameters are partially supported. If a query parameter used in a consumer test is not defined in the OAS, it will generate a warning. This allows consumers to deploy ahead of providers for certain use cases.Example
HeadersY
BodiesPFull schema support on JSON bodies only
Status codesY
LinkNIgnored
TagNIgnored
ExampleNIgnored
DiscriminatorPdiscriminator usage has the following requirements and limitations:
  • mapping in discriminator object is not supported.
  • "implicit" discriminator values are not supported.
  • oneOf keyword must be present in the same schema.
  • discriminator property should be required either on the top level, or in all oneOf subschemas.
  • each oneOf subschema must have the properties keyword with discriminator property. The subschemas should be either inlined
  • or
  • included as direct references (only $ref keyword without any extra keywords is allowed).
  • schema for discriminator property in each oneOf subschema must be const or enum, with unique values across all
  • subschemas.
  • Not meeting any of these requirements would fail schema compilation.

Keywords

See Keyword Support for additional information on this.

FeatureSupportedExample
anyOfYExample
anyOfYExample
allOfYExample

Encoding / Content Types

FeatureSupportedDescriptionExample
JSONYFull supportExample
XMLPWe don’t currently supported parsing and checking XML bodies, against defined schemas. Checks the content-type matches.Example
x-www-form-urlencoded Request BodiesNWe don’t currently supported parsing and checking URL encoded form bodies, against defined schemas. Checks the content-type matches.Example
multipart/form-dataNWe don’t currently supported parsing and checking multipart request bodies, against defined schemas. Checks the content-type matches.Example

Security Schemes

FeatureSupportedDescriptionExample
Security RequirementYapiKey, http, mutualTLS, oauth2, openIdConnectExample
BasicYOnly checks the presence of an Authorization header.
API Key (cookie)Y
API Key (header)Y
BearerYOnly checks the presence of an Authorization header
OpenIDPThe security scheme is allowed, but no additional checks are performed (e.g. checks for calls to a valid OIDC provider are not in scope, nor the checking of exchanged tokens)
OAuthPAs per OpenID
FlowsPBehaviour as above
MASSLPThe security scheme is allowed, but no additional checks are performed (e.g. no certificate checking on the requests can be performed for validity)
Multiple authentication typesNCurrently only one security scheme can be applied and tested. Support for “OR” and “AND”.
ScopesPAllowed and ignored for the purposes of our checks

Pact Support

Features

FeatureSupportedDescription
HTTPYHTTP based interactions
MessagesNMessages can’t be modelled appropriately in OpenAPI documents
PluginsNInteractions containing plugins or custom content
Matching RulesNIgnored. OAS schemas and types are the "matching rules" used in BDCT

Pact Specification Versions

VersionSupportedDescription
v1Yhttps://github.com/pact-foundation/pact-specification/tree/version-1
v1.1Yhttps://github.com/pact-foundation/pact-specification/tree/version-1.1
v2Yhttps://github.com/pact-foundation/pact-specification/tree/version-2
v3Yhttps://github.com/pact-foundation/pact-specification/tree/version-3
v4Yhttps://github.com/pact-foundation/pact-specification/tree/version-4