Validating Elements Against Schema

You can validate your API elements (documentation, tests, mock servers, or monitors) against the API schema. This helps keep your elements in sync with your API specification. If they do not match, you can see the list of issues that have been found in order to fix them.

This feature is available from Postman 7.15.0 and for OpenAPI 3.0 schemas only at this time.

This section outlines the following topics:

Validating elements

In this section, you can learn 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, Postman will automatically 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.

Accessing issues

You can access a summary of issues found during validation from the Postman app or the web dashboard. The summary will indicate the details of each issue so that you can address the underlying problem.

Accessing the issue summary from the Postman app

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

Understanding the issue summary

The validation summary lists all endpoints in your API element, regardless of whether they have issues, or if they are described in the API schema.

If an endpoint has been successfully validated against the API schema, you will see a green checkmark with a message indicating Validated against PATH.

endpoint validated

If an endpoint exists in the API element but isn't described in the API schema, you will see a red cross along with a message indicating Unable to validate. No matching path found in schema.

endpoint not found in schema

If syncing issues are found between the API element and the API schema, the validation summary will outline them under one of the following categories:

  • Request params
  • Request headers
  • Request URL
  • Request body
  • Example response body
  • Example response headers

Check out the complete list of possible issues.

endpoint has syncing issue

You can collapse or expand the list of issues by clicking the grey arrow at the top-right of the list.

List of possible issues

This section lists each type of issue that validation may raise along with examples. Issues fall into five categories:

Invalid type

Invalid type issues occur when the basic type doesn't match, or when the basic type matches but the schema is wrong.

The path variable "petId" needs to be of type boolean, but we found <integer>

Missing in schema

Missing in schema issues occur when an entity (variable, header, response headers) is not found in the schema you are validating against.

The header "isItCooper" was not found in the schema

Missing in request

Missing in request issues occur when an entity (variable, header) is not found in the request.

The required path variable "name" was not found in the transaction

Invalid body

Invalid body issues occur when the request body didn't match the one specified in the schema.

Body schema not found

Body schema not found issues occur when no application/json schema was found for the response.

Next steps

Your issue summary includes the details to address any problems validating against your schema. You can edit the relevant components of your API and validate again to see if the issues have been resolved.

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