This section lists the supported features and compatibility checks Swagger Contract Testing 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
| Feature |
Supported |
Description |
Example |
| Negative scenario testing |
Y |
Allow expectations for non-successful responses (e.g. 4xx, 5xx responses). |
Example |
| Inheritance and Polymorphism |
Y |
Inheritance is supported via the use of the discriminator keyword. |
Example |
| Content Negotiation (media types) |
Y |
Use 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 (
parameters) - 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 types |
Y |
Allows organisations to use custom (vendor) created content types. See content negotiation above for more. |
|
OpenAPI Support
Open API Specification Versions
| Format |
Supported |
| YAML |
Y |
| — |
— |
| JSON |
Y |
Resource Types
| Feature |
Supported |
Description |
| HTTP |
Y |
|
| — |
— |
— |
| Webhooks |
N |
Reverses the direction of the check, and doesn’t make sense (Pact can’t describe a consumer expecting a provider call) |
Full JSON Schema 2020-12 support, including resolving references ($ref)
| Feature |
Supported |
Description |
Example |
| Server Object |
N |
The servers are not used in request matching for 3.x.x OpenAPI descriptions, they are supported in OpenAPI 2.x. The comparison of Pact interactions to OAS endpoints doesn’t consider any basePath. However, you can specify a custom base URL using the x-opc-config-base-path setting. |
Example |
| — |
— |
— |
— |
| Security Filtering |
N |
Ignored |
|
| — |
— |
— |
— |
| info |
N |
Ignored |
|
| Contact |
N |
Ignored |
|
| License |
N |
Ignored |
|
| External Documentation |
N |
Ignored |
|
| Security Scheme |
P |
See below for details. |
|
| Relative References |
Y |
|
|
| Callbacks |
N |
Not supported |
|
| Parameter styles |
P |
See 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 parameters |
P |
Understands 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 parameters |
P |
Query parameters are 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. You can configure query parameter behavior with the x-opc-config-legacy-parser option. |
Example |
| Headers |
Y |
|
|
| Bodies |
P |
Full schema support on JSON bodies only |
|
| Status codes |
Y |
|
|
| Link |
N |
Ignored |
|
| Tag |
N |
Ignored |
|
| Example |
N |
Ignored |
|
| Discriminator |
P |
discriminator 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 withdiscriminator 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 allsubschemas. - Not meeting any of these requirements would fail schema compilation.
|
|
Keywords
See Keyword Support for additional information on this.
| Feature |
Supported |
Description |
Example |
| JSON |
Y |
Full support |
Example |
| — |
— |
— |
— |
| XML |
P |
We don’t currently supported parsing and checking XML bodies, against defined schemas. Checks the content-type matches. |
Example |
x-www-form-urlencoded Request Bodies |
N |
Checks if the body matches the schema. |
Example |
multipart/form-data |
N |
By default, multipart bodies are not checked. May be enabled using the x-opc-config-disable-multipart-formdata setting. |
Example |
By default, the schema for security schemes is not checked. This may be enabled using the x-opc-config-no-authorization-schema setting.
| Feature |
Supported |
Description |
Example |
| Security Requirement |
Y |
apiKey,http, mutualTLS, oauth2, openIdConnect |
Example |
| — |
— |
— |
— |
| Basic |
Y |
Only checks the presence of an Authorization header according to RFC 7617. |
|
| API Key (cookie) |
Y |
|
|
| API Key (header) |
Y |
|
|
| Bearer |
Y |
Checks the presence and format of an Authorization header according to RFC 6750. |
|
| OpenID |
P |
The 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) |
|
| OAuth |
P |
As per OpenID |
|
| Flows |
P |
Behaviour as above |
|
| MASSL |
P |
The 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 types |
N |
Currently, only one security scheme can be applied and tested. Support for “OR” and “AND”. |
|
| Scopes |
P |
Allowed and ignored for the purposes of our checks |
|
Pact Support
Features
| Feature |
Supported |
Description |
| HTTP |
Y |
HTTP based interactions |
| — |
— |
— |
| Messages |
N |
Messages can’t be modelled appropriately in OpenAPI documents |
| — |
— |
— |
| Plugins |
N |
Interactions containing plugins or custom content |
| Matching Rules |
N |
Interactions containing plugins or custom content |
Pact Specification Versions