validator

Overview ¶

Package validator provides validation for OpenAPI Specification documents.

The validator supports OAS 2.0 through OAS 3.2.0, performing structural validation, format checking, and semantic analysis against the specification requirements. It includes best practice warnings and strict mode for enhanced validation.

Quick Start ¶

Validate a file with warnings enabled using functional options:

result, err := validator.ValidateWithOptions(
	validator.WithFilePath("openapi.yaml"),
	validator.WithIncludeWarnings(true),
)
if err != nil {
	log.Fatal(err)
}
if !result.Valid {
	fmt.Printf("Found %d error(s)\n", result.ErrorCount)
}

Or create a reusable validator instance:

v := validator.New()
v.StrictMode = true
result, _ := v.Validate("api1.yaml")
result, _ := v.Validate("api2.yaml")

Features ¶

The validator checks document structure, required fields, format validation (URLs, emails, media types), semantic constraints (operation ID uniqueness, parameter consistency), and JSON schemas. Path validation includes checking for malformed templates (unclosed braces, reserved characters, consecutive slashes) and REST best practices (trailing slashes generate warnings when IncludeWarnings is enabled). See the examples in example_test.go for more usage patterns.

Validation Output ¶

ValidationResult contains:

• Valid: Boolean indicating if document is valid
• Version: Detected OpenAPI version (e.g., "3.0.3")
• Errors: Validation errors with JSON path locations
• Warnings: Best practice warnings (if IncludeWarnings is true)
• ErrorCount, WarningCount: Issue counts

See the exported ValidationError and ValidationResult types for complete details.

Related Packages ¶

Validation typically follows parsing:

• github.com/erraggy/oastools/parser - Parse specifications before validation
• github.com/erraggy/oastools/fixer - Fix common validation errors automatically
• github.com/erraggy/oastools/converter - Convert validated specs between OAS versions
• github.com/erraggy/oastools/joiner - Join validated specs into one document
• github.com/erraggy/oastools/differ - Compare specifications and detect breaking changes
• github.com/erraggy/oastools/generator - Generate Go code from validated specifications
• github.com/erraggy/oastools/builder - Programmatically build specifications

package main

import (
	"fmt"
	"log"
	"path/filepath"

	"github.com/erraggy/oastools/validator"
)

func main() {
	// Create a validator with strict mode and warnings enabled
	v := validator.New()
	v.IncludeWarnings = true // Include best-practice warnings
	v.StrictMode = true      // Enforce strict validation rules

	// Validate an OpenAPI specification
	testFile := filepath.Join("testdata", "petstore-3.0.yaml")
	result, err := v.Validate(testFile)
	if err != nil {
		log.Fatal(err)
	}

	// Separate errors from warnings by severity
	errors := 0
	warnings := 0

	for _, issue := range result.Errors {
		// Severity levels: SeverityCritical=3, SeverityError=2, SeverityWarning=1, SeverityInfo=0
		switch issue.Severity {
		case validator.SeverityCritical:
			errors++ // Critical issues are also errors
			fmt.Printf("CRITICAL [%s]: %s\n", issue.Path, issue.Message)
		case validator.SeverityError:
			errors++
			fmt.Printf("ERROR [%s]: %s\n", issue.Path, issue.Message)
		case validator.SeverityWarning:
			warnings++
			fmt.Printf("WARNING [%s]: %s\n", issue.Path, issue.Message)
		case validator.SeverityInfo:
			fmt.Printf("INFO [%s]: %s\n", issue.Path, issue.Message)
		}
	}

	// Summary
	fmt.Printf("\nValidation complete:\n")
	fmt.Printf("- Valid: %v\n", result.Valid)
	fmt.Printf("- Errors: %d\n", errors)
	fmt.Printf("- Warnings: %d\n", warnings)

	// StrictMode treats warnings as errors for result.Valid
	// IncludeWarnings populates result.Errors with warning-level issues
}