NAME

OpenAPI::Linter - Validate and lint OpenAPI specifications

VERSION

Version 0.15

SYNOPSIS

use OpenAPI::Linter;

# Create a linter from a file
my $linter = OpenAPI::Linter->new(spec => 'openapi.yaml');

# Or from a hashref
my $linter = OpenAPI::Linter->new(spec => $openapi_hash);

# Find issues in the specification
my @issues = $linter->find_issues;

# Filter issues by level or pattern
my @warnings = $linter->find_issues(level => 'WARN');
my @path_issues = $linter->find_issues(pattern => qr/paths?/i);

# Validate against JSON Schema
my @schema_errors = $linter->validate_schema;

DESCRIPTION

OpenAPI::Linter provides comprehensive validation and linting for OpenAPI specifications. It checks both structural correctness against the official JSON Schema and performs additional linting for best practices and common issues.

The module supports OpenAPI versions 3.0.x and 3.1.x, automatically detecting the specification version from the provided document.

METHODS

new

my $linter = OpenAPI::Linter->new(spec => $file_path_or_hashref);
my $linter = OpenAPI::Linter->new(spec => $hashref, version => '3.0.3');

Creates a new OpenAPI::Linter instance. The constructor accepts:

spec

Required. Either a file path to an OpenAPI specification (YAML or JSON) or a hash reference containing the parsed OpenAPI specification.
version

Optional. Explicitly set the OpenAPI version. If not provided, the version will be auto-detected from the specification.

find_issues()

Finds and returns linting issues in the OpenAPI specification. Returns a list of issue hashes in list context, or an array reference in scalar context.

Each issue hash contains:

{
    level   => 'ERROR' | 'WARN',  # Issue severity level
    message => 'Human readable description of the issue'
}

Parameters:

level

Filter issues by severity level. Either ERROR or WARN.
pattern

Filter issues by message pattern (regular expression).

my @all_issues = $linter->find_issues;
my @issues = $linter->find_issues(level => 'ERROR');
my @issues = $linter->find_issues(pattern => qr/missing/i);
my @issues = $linter->find_issues(level => 'WARN', pattern => qr/description/);

validate_schema()

my @schema_errors = $linter->validate_schema;
my $schema_errors = $linter->validate_schema;

Validates the OpenAPI specification against the official JSON Schema for the detected OpenAPI version. Returns a list of validation errors in list context or an array reference in scalar context.

This method uses JSON::Validator to perform schema validation. It applies filtering to address validation discrepancies where valid OpenAPI specifications (per the OpenAPI Specification text) are incorrectly flagged as invalid.

Validation Discrepancies

When validating against the published schemas, JSON::Validator produces errors for constructs that are explicitly valid according to the OpenAPI Specification v3.0.3.

Example: This valid parameter definition:

parameters:
  - name: id
    in: path        # Valid per OpenAPI Spec
    required: true  # Valid boolean per OpenAPI Spec
    schema:
      type: string

Produces these validation errors:

/in: Not in enum list: query, header, cookie
/required: Not in enum list: true
/$ref: Missing property

The OpenAPI Specification states:

"in (string, REQUIRED): The location of the parameter. Possible values are query, header, path or cookie."

Reference: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameter-object

Despite path being explicitly listed as valid, validation fails.

Filtering Approach

To ensure valid OpenAPI specifications validate correctly, this method filters errors by:

1. Identifying error patterns matching known discrepancies
2. Extracting the actual value from the specification
3. Checking if the value is valid per the OpenAPI Specification text
4. Removing the error only if the value is explicitly documented as valid

Important: Invalid values still generate errors. For example, in: invalid_location will correctly produce a validation error.

Filtered Patterns

Parameter 'in' field

Error pattern: /in: Not in enum list

Filtered when: actual value is 'path' (valid per https://spec.openapis.org/oas/v3.0.3.html#fixed-fields-9)
Parameter 'required' field

Error pattern: /required: Not in enum list

Filtered when: actual value is a boolean (true, false, 1, 0)
Inline parameter definitions

Error pattern: /$ref: Missing property

Filtered when: parameter has both name and in fields (valid inline definition)

Root Cause

The exact cause of these discrepancies is unclear and could involve:

Issues in the published JSON Schema files
JSON::Validator's interpretation of those schemas
Interactions between validator and schema

This method takes a pragmatic approach: it defers to the authoritative OpenAPI Specification text when determining validity, ensuring users get accurate validation results for their specifications.

_filter_known_false_positives

@filtered = $self->_filter_known_false_positives(@errors);

Internal method that filters out false positive errors. This method validates that errors are truly false positives by checking the actual spec values before filtering.

This is a targeted approach that only removes errors when the actual value in the spec is valid per the OpenAPI specification

All other errors, including similar-looking errors with invalid values, are preserved.

The key insight is that JSON::Validator reports the path to the FIELD with the error (e.g., /paths/~1test/get/parameters/0/in), so we need to navigate to the parent object and check the actual value of that field.

_extract_value_from_path

Internal helper to extract actual value from spec using JSON pointer path.

This method handles JSON Pointer syntax (RFC 6901) with proper decoding of escape sequences. It also handles a quirk where JSON::Validator sometimes produces ~001 instead of ~1 in error paths (observed with $ref-related errors).

_extract_parameter_from_path

Internal helper to extract parameter object from spec using JSON pointer path.

_is_valid_boolean

Internal helper to check if a value is a valid boolean.

APPLICATION

openapi-linter is a command-line tool that validates OpenAPI specifications for both structural correctness and best practices. It uses the OpenAPI::Linter module to perform comprehensive checks on OpenAPI documents.

The tool can operate in two modes:

1. Linting mode (default): Checks for best practices, missing required fields and common issues in OpenAPI specifications.
2. Schema validation mode: Validates the specification against the official OpenAPI JSON Schema for the detected version.

OPTIONS

--spec specfile: Required. Path to the OpenAPI specification file. The file can be in either YAML (.yaml, .yml) or JSON (.json) format.
--version version: Specify the OpenAPI version explicitly (e.g., 3.0.3, 3.1.0). If not provided, the version will be auto-detected from the openapi field in the specification.
--json: Output results in JSON format instead of human-readable text. This is useful for programmatic consumption of the results.
--validate: Run schema validation instead of lint checks. This mode validates the specification against the official OpenAPI JSON Schema rather than performing custom linting rules.
--help: Display this help message and exit.

EXAMPLES

Basic Usage

openapi-linter --spec api.yaml

Run linting checks on api.yaml and display results in human-readable format.

Schema Validation

openapi-linter --spec api.json --validate

Validate api.json against the official OpenAPI JSON Schema.

JSON Output

openapi-linter --spec api.yaml --json

Run linting checks and output results in JSON format for programmatic processing.

Specific Version

openapi-linter --spec api.yaml --version 3.1.0

Run linting checks assuming OpenAPI version 3.1.0, overriding auto-detection.

OUTPUT FORMATS

Human Readable Output (Default)

The default output format displays issues in a readable format:

[ERROR] Missing info.title
[WARN] Missing info.description
[ERROR] Missing info.version

Summary: 2 ERRORs, 1 WARN

Exit Codes

0: No issues found
1: Issues found (errors and/or warnings)
2: Usage error

JSON Output

When using --json, the output is structured JSON:

{
    "summary": {
        "errors": 2,
        "warnings": 1
    },
    "issues": [
        {
            "level": "ERROR",
            "message": "Missing info.title"
        },
        {
            "level": "WARN",
            "message": "Missing info.description"
        },
        {
            "level": "ERROR",
            "message": "Missing info.version"
        }
    ]
}

LINTING CHECKS

When running in linting mode (default), the tool checks for:

Required root elements (openapi, info, paths)
Required info object fields (title, version)
Recommended info object fields (description, license)
Operation descriptions for all paths and methods
Schema type definitions and property descriptions

SCHEMA VALIDATION

When using --validate, the tool validates the specification against the official OpenAPI JSON Schema for the detected version. This checks:

Structural correctness of the specification
Data types and format compliance
Required fields according to the OpenAPI specification
Valid references and schema composition

SUPPORTED OPENAPI VERSIONS

OpenAPI 3.0.0, 3.0.1, 3.0.2, 3.0.3
OpenAPI 3.1.0, 3.1.1

DIAGNOSTICS

"spec = HASHREF required if no file provided">: The spec parameter to new must be either a file path or a hash reference containing the OpenAPI specification.
"Unsupported OpenAPI version: %s": The OpenAPI version specified in the document or provided to the constructor is not supported.

AUTHOR

Mohammad Sajid Anwar, <mohammad.anwar at yahoo.com>

REPOSITORY

https://github.com/manwar/OpenAPI-Linter

BUGS

Please report any bugs or feature requests through the web interface at https://github.com/manwar/OpenAPI-Linter/issues. I will be notified and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc OpenAPI::Linter

You can also look for information at:

BUG Report

https://github.com/manwar/OpenAPI-Linter/issues
CPAN Ratings

http://cpanratings.perl.org/d/OpenAPI-Linter
Search MetaCPAN

https://metacpan.org/dist/OpenAPI-Linter/

LICENSE AND COPYRIGHT

This program is free software; you can redistribute it and / or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License.By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you,you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement,then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

To install OpenAPI::Linter, copy and paste the appropriate command in to your terminal.

cpanm

cpanm OpenAPI::Linter

CPAN shell

perl -MCPAN -e shell
install OpenAPI::Linter

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

METHODS

new

find_issues()

validate_schema()

Validation Discrepancies

Filtering Approach

Filtered Patterns

Root Cause

_filter_known_false_positives

_extract_value_from_path

_extract_parameter_from_path

_is_valid_boolean

APPLICATION

OPTIONS

EXAMPLES

Basic Usage

Schema Validation

JSON Output

Specific Version

OUTPUT FORMATS

Human Readable Output (Default)

Exit Codes

JSON Output

LINTING CHECKS

SCHEMA VALIDATION

SUPPORTED OPENAPI VERSIONS

DIAGNOSTICS

SEE ALSO

AUTHOR

REPOSITORY

BUGS

SUPPORT

LICENSE AND COPYRIGHT

Module Install Instructions