Skip to main content

OpenAPI Specification Contracts

Providers may specify an OpenAPI Specification as a Provider Contract, enabling teams to reuse existing tools and processes.

Supported versions​

VersionSupported?
Swagger (1.x)❌
Swagger (2.0)✅
OAS 3.0.x (up to 3.0.3)✅
OAS 3.1.x (up to 3.1.0)✅

Limitations and Considerations​

PactFlow transforms your OAS​

PactFlow needs to perform a number of minor modifications to the document prior to validation to perform its compatibility checks and support many OAS features. In most cases, they will be transparent to you. You can find more information here.

Document Limitations​

When using the OpenAPI Specifications as a Provider Contract, you should know the following limitations.

  • The OAS must be a valid YAML or JSON file. PactFlow will give an error if an invalid document is provided.
  • OAS documents must not be split across multiple files. You should combine the documents together, using tools like OpenAPI Merge or speccy. That is, PactFlow can not resolve remote references to files, and will not resolve URL references.
  • YAML formatted OAS documents must not use anchors, due to the potential security issues (see YAML bomb for more). If your auto-generated specs have anchors, you can pre-process them via tools like spruce, that will expand them for you.

Other Considerations​

  • It is recommended to set additionalProperties to true on request items to align with Postel's Law.
  • Implementing a spec is not the same as being compatible with a spec (read more). Most tools only tell you that what you’re doing is not incompatible with the spec.
  • You are responsible for ensuring sufficient OAS coverage. To highlight this point, in our Dredd example, we do not test the 404 case on the provider, but the consumer has a pact for it and it's tests still pass! NOTE: We plan to address this problem in the future via our OAS Testing Tool.