schema-validator.md

Schema Validator Implementation

The OneBusAway API Validator implements OpenAPI schema validation using the kin-openapi library to validate API responses against the formal OpenAPI 3.0 specification.

kin-openapi Library

The validator leverages the kin-openapi library, which provides:

• Specification Loading: Parse and validate OpenAPI YAML/JSON specifications
• Request/Response Validation: Comprehensive validation against schema definitions
• Router Integration: Path matching and parameter extraction

For detailed documentation, visit their official documentation.

Implementation

The schema validator is implemented in the internal/schemavalidator package with a core OpenAPIValidator struct that encapsulates:

• Loader: OpenAPI specification loader with context support
• Document: Parsed and validated OpenAPI specification
• Router: Path matching router for endpoint resolution
• Client: Optional OBA client for live request execution

The validator initialization process:

1. Loads and parses the OpenAPI YAML specification
2. Validates the specification itself for correctness
3. Configures server URLs for local testing
4. Sets up router for path matching

Validation Process

The core validation process:

1. Route Resolution: Matches the request URL to the OpenAPI specification path
2. Parameter Extraction: Extracts path parameters for validation context
3. Response Parsing: Parses the JSON response body
4. Schema Validation: Validates response against defined schemas

The validator supports both direct response validation and request-based validation for live API testing.

OpenAPI Specification

The validator uses the comprehensive OpenAPI 3.0 specification defined in openapi.yml, which provides:

• Complete API Documentation: All endpoints, parameters, and responses
• Schema Definitions: Reusable component schemas with inheritance
• Validation Rules: Type constraints, required fields, and formats
• Response Templates: Standardized response wrapper patterns