Validating APIs

You can validate your API schema in Postman, and validate your elements (documentation, tests, mock servers, monitors) against a schema. This helps keep your API well-defined and ensure that your elements are in sync with your schema. If there is a validation error on the schema or elements do not match it, Postman will present a list of issues that have been found, as well as fixes for these issues. You can then apply fixes to the API elements and revalidate them.

Validation is available for OpenAPI 3.0 schemas.

Validating schema

Postman will indicate validation errors on your API schema as you edit it in the Define tab.

Schema error

The pane below the schema editing area will indicate issues—you can hide and show the error view as you work.

Schema errors hidden

Each error will indicate the type, the line it occurs on, and details of the issue. You can also hover over the error inline in the editor to see information as you type.

Schema error list

Note that sometimes a single error in your schema will cause more than one issue to appear in the list. As you fix your errors you will see the validation issues disappear.

If there is an issue with your schema JSON or YAML syntax, you will see a warning—look for errors indicated in the editor and hover for more detail. Postman will only be able to validate your schema elements if the JSON or YAML is itself well-formed.

Invalid JSON

If there are no errors, Postman will indicate that your schema is valid.

Valid schema

Validating elements

This section outlines the pre-requisites for validating your elements against an API schema, when validations are triggered, and how to trigger one manually.

For validations to execute, you need the following elements in place:

Once the validation is complete, a status will appear next to the element indicating a checkmark if no issues have been found, or a warning message stating Issues found.

When you add a new element to an API, you need to trigger a validation to check it against the current API schema. The results of the validation will appear next to the element.

add new element validation

You can also trigger a new validation of your element manually in the following cases:

  • Re-validating after editing your schema and/or your linked element
  • Adding a new schema to an API that already has elements linked to it

You can do so by navigating to your element (eg. Test Suite), clicking the validation status, then Validate Again.

re validating element

You can also trigger a validation from the issues list by clicking Validate again at the top-right of the page.

Validating requests

If you want your requests to be validated, your collection must be linked to an API.

A collection is linked to an API if you generate it from a schema or add it as a relation to an existing API.

Postman will validate a request when it is sent. If issues are found, you will see a warning message showing the number of issues next to the name of the request.

validating request

Validation is version-specific, and will be performed against the schema of the particular version of the API linked with the collection. If one version of a collection is linked to more than one version of an API, Postman will select the schema from the latest created version of API for validation.

Accessing issues

You can review the issues found during validation from the Postman app or the web dashboard.

Accessing the issue summary from the Postman app

If an issue arises when you run a request, click the warning message next to the name of the request (e.g. 1 issue). This will open a side-panel on the right indicating detailed information about which component of the request is affected and what the issue itself is:

  • A direct link to the API against which the request is validated—click the link to open the API within the Postman app.
  • More details on where the issue lies within the request.

You can click a specific issue to access the relevant request component.

viewing issues

If your issue relates to another element, navigate to your API by clicking APIs in the app sidebar, then select your API from the list. Open the tab containing the element you want to see issues for (either Develop, Test or Observe).

You will see a status indicating whether issues have been found during validation next to the element. If there are issues, view them by clicking Issues found > View issues. This will take you to a page on the web dashboard summarizing validation issues.

open list of issues app

Accessing the issue summary from the web dashboard

You can access the summary of validation issues from the web dashboard by navigating to your API, then selecting the tab containing the element you want to see issues for (either Develop, Test or Observe).

You will see a status indicating whether any issues have been found during validation next to the element. If there are issues, you can display them by hovering over Issues found, then clicking View issues. This will redirect you to a page summarizing the issues.

open list of issues dashboard

Updating API elements

The summary will indicate the details of each issue and provide fixes that you can automatically apply to the corresponding API element.

Understanding the issue summary

The validation summary lists all the issues found between the generated collection and the API schema. You can select suggested changes to make to the collection.

The left sidebar gives you a summary of issues and allows you to navigate between them. The summary includes the following details:

  • The request name along with the number of issues found in that request.
  • The request elements with issues, along with the issue type and number of occurrences.

review issues sidebar

You can click on the request name or the request element to navigate directly to the corresponding issue(s).

The right-hand side of the review contains details on what changes need to be made for the API element to be in sync with the schema again. Elements highlighted in red will be removed from the collection. Elements highlighted in green will be added.

For example, if a user updates the description of an endpoint in the schema, the summary will show the text that has been removed in red, and what has been added in green.

updating description

You can collapse or expand the list of changes by clicking the arrows next to the request or element name.

Applying changes to API elements

You can individually select the changes to be applied to the API element as you review them. Navigate to the change you want to apply and select Make this change to the collection next to it. Repeat the same action for each change you would like to apply.

When you're done selecting the changes to apply, click Confirm Changes to Collection.

selecting some changes

Alternatively, you can choose to apply all changes by clicking Select all changes, then Confirm Changes to Collection.

selecting all changes

You can access the updated API element by clicking View Updated Collection from the confirmation screen. If you didn't apply all changes, you can also review the remaining issues by clicking View Remaining Issues.

If you've been using this feature, the Postman team would like to hear from you! You can provide feedback on the community forum.

Next steps

In addition to keeping your API elements in sync with a schema, you can analyze and utilize reporting to promote understanding of how your APIs are performing.