Validate an API specification

As you edit your specification, Postman identifies syntax errors, such as wrong data types and nesting, and shows details about the errors so you can correct them. Postman also identifies API governance issues in OpenAPI specifications, based on the rules configured for your team.

You can also run a full lint check with the Postman CLI directly from the specification editor, which checks both syntax and governance rules in one pass and can be added to a CI/CD pipeline.

Below the specification editor, Postman displays the validation pane in the Issues tab, which is selected by default. The validation pane has two sections: Syntax and Governance. Expand either section to view issues in your specification.

The validation pane only shows syntax errors and governance rule violations for the specification file you’re editing.

View syntax errors in your specification

Postman automatically identifies syntax errors as you edit your API specification. Errors can include missing fields, malformed field names, wrong data types, wrong nesting, or other issues. For Postman to be able to check your specification elements, you must use valid JSON or YAML.

To view any syntax errors, click Syntax in the validation pane. Each syntax error shows the number of times Postman found it in the specification, where the error occurs, details about the error, and the severity. Click a syntax error to go to its location in the specification.

If your specification is organized into multiple files and folders, every instance of the syntax error also has the path to its respective file. Click a syntax error to go to the file.

View rule violations in your specification

As you edit your OpenAPI specification, Postman automatically checks it against the Postman API Governance rules configured for your team.

To view any governance rule violations, click Governance in the validation pane. Each rule violation shows the number of times Postman found it in the specification, where the rule violation occurs, details about the rule violation, and the severity. Click a governance rule violation to go to its location in the specification.

If your specification is organized into multiple files and folders, every instance of the rule violation will also have the path to its respective file. Click a governance rule violation to go to the file.

API Governance Managers can view detailed metrics on API Governance rule compliance in your specifications.

Run a spec lint check with the Postman CLI

In addition to the automatic checks in the editor, you can run a one-time lint check against your specification using the Postman CLI. A spec lint checks both syntax and, on Enterprise plans, API Governance rules in a single command, and reports results back to Postman.

To run a spec lint from the editor, do the following:

1. Expand Specifications in the sidebar, then select the specification you want to check.
2. In the workbench, click Lint in the upper right.
3. In the Spec Lint pane, select Terminal to run the check locally, or CI/CD Pipeline for instructions on running it in a pipeline.
4. If you haven’t already, install the Postman CLI. Click Install in Terminal to run the install command in the built-in terminal.
5. Click to copy the pre-filled postman spec lint command for this specification, or click Run in Terminal to run it directly.

Learn more about the postman spec lint command, including how to change the output format and use it in a CI/CD pipeline.