libopenapi-validator

The validator is designed to validate several different entities against an OpenAPI 3+ specification:

• http.Request: Validates an incoming HTTP request.
• http.Response: Validates an outgoing HTTP response.
• libopenapi.Document: Validates the OpenAPI document itself.
• base.Schema: Validates a specific schema against a JSON or YAML blob or an unmarshalled object.

To automate OpenAPI validation during your git workflow, you can install a pre-commit hook:

pre-commit install

To use the libopenapi-validator module in your Go project, install it using go get:

go get github.com/pb33f/libopenapi-validator

The validate command is a CLI tool used to check if an OpenAPI Specification (OAS) document (YAML or JSON) conforms to the OpenAPI specification using libopenapi-validator.

Usage: validate [OPTIONS] <file>

Examples:

Validate a YAML file using the ECMAScript regex engine:

go run main.go --regexengine=ecmascript ./my-api-spec.yaml

Validate a YAML file by pre-converting it to JSON (useful for complex mappings):

go run main.go --yaml2json ./my-api-spec.yaml

Use validator.NewValidatorFromV3Model to create a validator instance. You can pass several configuration options to customize behavior, such as strict server matching or standard body decoders.

Available Configuration Options (Examples):

• config.WithStrictServerMatching(): Enables strict server matching.
• config.WithStandardBodyDecoders(): Uses standard body decoders.
• config.WithRejectUnsupportedBodyContent(): Rejects unsupported body content.
• config.WithRequestDefaults(): Applies request defaults.

v := validator.NewValidatorFromV3Model(&model.Model,
    config.WithStrictServerMatching(),
    config.WithStandardBodyDecoders(),
    config.WithRejectUnsupportedBodyContent(),
    config.WithRequestDefaults(),
)

To enable or disable the application of default values to the request body, you must configure the ValidateRequestBody option within your validator's options.

Note that for request body defaults to work, your validator must have a valid BodyRegistry configured with appropriate Decoder and Encoder implementations for the Content-Type being used in the request.

The validate CLI tool supports the following flags:

• --regexengine: Specifies a custom regex engine. Defaults to re2. Supported values include: none, ignorecase, multiline, explicitcapture, compiled, singleline, ignorepatternwhitespace, righttoleft, debug, ecmascript, re2, unicode.
• --yaml2json: Converts YAML files to JSON before validation. This is recommended for OpenAPI specs with deeply nested schema definitions or complex allOf, oneOf, or anyOf structures to avoid ambiguous errors caused by map[interface{}]interface{} structures in libopenapi.

# Example: Use ecmascript regex engine
go run github.com/pb33f/libopenapi-validator/cmd/validate@latest --regexengine=ecmascript <file>

# Example: Enable YAML to JSON conversion
go run github.com/pb33f/libopenapi-validator/cmd/validate@latest --yaml2json <file>

You can validate an OpenAPI specification file directly from the command line using the validate command. This is useful for CI/CD pipelines or manual checks.

Usage: go run github.com/pb33f/libopenapi-validator/cmd/validate@latest [--regexengine] [--yaml2json] <file>

To start validating OpenAPI 3+ documents, use NewValidator. This function takes a libopenapi.Document and optional config.Option arguments. It builds a V3 model from the document and returns a Validator instance. If the document cannot be converted to a V3 model, it returns an error.

Note: The validator internally builds a radix tree for efficient path lookups and warms schema caches to optimize runtime performance.

import (
	"github.com/pb33f/libopenapi"
	"github.com/pb33f/libopenapi-validator"
)

// Assuming 'doc' is a valid libopenapi.Document
validator, errs := validator.NewValidator(doc)
if len(errs) > 0 {
	// handle errors
}
// Use validator to perform checks

Use compatibilityPath to derive a relative path from an *http.Request based on the base URLs defined in an OpenAPI *v3.Document.

This is useful when the incoming request URL includes the full server base path (e.g., https://api.example.com/v1/users) and you need to strip the base path (e.g., /v1) to get the path relative to the API root (e.g., /users).

It iterates through the document.Servers and, if a match is found where the request path starts with the server's URL path, it trims that prefix. It also preserves URL fragments.

// Returns the path relative to the server base URL
relPath := router.CompatibilityPath(request, document)

The validator uses an internal mechanism to stage defaults. While the primary entry point for users is typically a high-level validation method, the underlying logic relies on validateWithRequestDefaults.

When defaults are applied, the following fields of the *http.Request are updated if validation passes:

• URL (including Query parameters)
• Header
• Body
• GetBody
• ContentLength