Ensure consistency between your collection and the API definition

You can validate collections that are linked to an API to make sure the API implementation is consistent with the API definition. Postman automatically compares requests and saved examples in the collection to the API definition and alerts you to any inconsistencies. Postman also validates responses when you send a request from the collection.

To help keep your API well defined, you can check your API definition as you work on it in Postman. As you edit your API definition, Postman lists any syntax errors based on the definition type. Postman also identifies any API governance and security issues based on the rules configured for your team.

Validating requests and responses

For collections linked to an API, Postman can automatically detect any inconsistencies between the requests and saved examples in the collection and the API definition. Postman can also compare responses received from the server to the API definition to make sure the API implementation aligns with the API design. Postman displays a warning for each detected issue. Select a warning to view the source of the issue so you can resolve it.

Request validation is supported for OpenAPI 3.0 and 3.1 definitions.

Enabling request validation

When request validation is enabled, Postman automatically checks for validation issues whenever you open a request, change a request or a saved example, or change the API definition. Postman also checks for issues when you send a request, and the response is considered as a saved example.

To enable request validation, do the following:

1. Select the settings icon in the header, then select Settings.
2. Turn on the toggle next to Request Validation.

Viewing validation issues

To validate requests, saved examples, and responses, your collection must be linked to an API. Learn more about adding a collection to an API.

If Postman detects validation issues, an orange dot displays in the sidebar next to the collection, folder, request, or saved example with the issue. Select the element to open it. A warning icon displays in the tab next to the element's name showing the number of issues found in the element.

To view the list of validation issues, select the warning icon in the tab of the collection, folder, request, or saved example. Postman provides details for each issue, including the element with the issue and details about the problem.

Select an issue to view the element where the issue was detected. To resolve the issue, you can change the request or saved example, or you can change the API definition. After you save your changes, if the problem is corrected, the issue disappears.

If your collection has requests that are different from your API definition, you can automatically update the collection based on the definition. Learn more about keeping a collection in sync with an API.

Validation triggers

The table below lists changes you can make to collections or API definitions, and it notes which changes will result in validation issues if request validation is enabled.

Source	Change	Validation issue
Collection	Add a request	No
Collection	Remove a request	No
Collection	Add a query parameter to an existing request	Yes
Collection	Add a path parameter to an existing request	Yes
Collection	Remove a path parameter from an existing request	No
Collection	Add a property to the request body	No
Collection	Change the data type of a request body property	Yes
Collection	Change the name of a required property in the request body	Yes
Collection	Update request or collection documentation	No
Collection	Add an example	Yes
Collection	Remove an example	No
Definition	Add an endpoint	Yes
Definition	Remove an endpoint	Yes
Definition	Remove a path parameter	No
Definition	Add a required query parameter to an endpoint	Yes
Definition	Add a required property to the request body	Yes
Definition	Change the data type of a request body property	Yes
Definition	Update the request summary	Yes
Definition	Update the request description	No
Definition	Add an example response	Yes
Definition	Remove an example response	Yes

Viewing syntax errors in your API definition

Postman automatically identifies syntax errors as you edit your API definition. Errors can include missing fields, malformed field names, incorrect data types, incorrect nesting, or other API definition issues.

Postman can identify syntax errors for OpenAPI 2.0, 3.0, and 3.1 and WSDL 1.1 and 2.0 definitions. For Postman to be able to check your definition elements, the JSON or YAML must be well formed.

To view any syntax errors, select Syntax next to Violations found in definition. Each error shows the error type, the line on which it occurs, and details about the issue. Select an error to highlight it in the editor. You can also get more information by hovering over the error in the editor.

Sometimes a single error in your definition will cause more than one issue to appear in the list. As you fix the errors, the issues disappear.

Viewing rule violations in your API definition

This feature is available on Postman Enterprise plans.

As you create your API definition in the editor, Postman automatically checks it against the Postman API Governance and API Security rules configured for your team. Postman displays any rule violations below the editor. Resolving these issues enables you to improve your API definition.

To learn more about the supported API description formats, the rules preconfigured in Postman, and how to create new rules, see Rule violations in the API definition.

To view any rule violations, select Rule next to Violations found in definition. Each rule violation is on its own line and includes the violation Name and the rule type (Governance or Security). The number next to the rule name tells you how many times Postman found the rule violation in your API definition.

Select the number to inspect each rule violation. Every instance of the rule violation has a brief description of the issue and the line in the file where the rule violation occurs. When you select a rule violation, Postman highlights the section of the definition that triggered it.

To learn more about the rule violation and get information about how to fix it, select Possible fix next to the rule description. This will open the relevant Learning Center page.

When you make updates to your API definition, Postman re-checks it. If your changes resolve the issue, Postman removes the rule violation from the list.

Hiding rule violations

To hide a rule violation for the API definition, do the following:

1. Select Hide next to the rule violation.

   

2. Select a reason that you want to hide it, then select Hide.

   

This will hide the rule violation for the current API. If there is more than one violation of a specific rule, you can hide each instance individually.

To hide a rule violation globally, you can use either configurable API Governance rules or configurable API Security rules.

When you or another member of your team hides a rule violation, Postman shows a message in the editor's Rule tab to indicate how many are hidden.

To turn a rule back on later, do the following:

1. Select Review.
2. Review your hidden rules and select the eye icon next to the one you want to turn back on.