schemav2validator

Schemav2Validator Plugin

Validates Beckn protocol requests against OpenAPI 3.1 specifications using kin-openapi library.

Features

• Validates requests against OpenAPI 3.1 specs
• Supports remote URL and local file loading
• Automatic external $ref resolution
• TTL-based caching with automatic refresh
• Generic path matching (no hardcoded paths)
• Direct schema validation without router overhead

Configuration

schemaValidator:
  id: schemav2validator
  config:
    type: url
    location: https://example.com/openapi-spec.yaml
    cacheTTL: "3600"

Configuration Parameters

How It Works

1. Load Spec: Loads OpenAPI spec from configured URL at startup
2. Extract Action: Extracts action from request context.action field
3. Find Schema: Searches all paths and HTTP methods in spec for schema with matching action:
   • Checks properties.context.action.enum for the action value
   • Also checks properties.context.allOf[].properties.action.enum
   • Stops at first match
4. Validate: Validates request body against matched schema using Schema.VisitJSON() with:
   • Required fields validation
   • Data type validation (string, number, boolean, object, array)
   • Format validation (email, uri, date-time, uuid, etc.)
   • Constraint validation (min/max, pattern, enum, const)
   • Nested object and array validation
5. Return Errors: Returns validation errors in ONIX format

Action-Based Matching

The validator uses action-based schema matching, not URL path matching. It searches for schemas where the context.action field has an enum constraint containing the request's action value.

Example OpenAPI Schema

paths:
  /beckn/search:
    post:
      requestBody:
        content:
          application/json:
            schema:
              properties:
                context:
                  properties:
                    action:
                      enum: ["search"]  # ← Matches action="search"

Matching Examples

External References

The validator automatically resolves external $ref references in OpenAPI specs:

# Main spec at https://example.com/api.yaml
paths:
  /search:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: 'https://example.com/schemas/search.yaml#/SearchRequest'

The loader will automatically fetch and resolve the external reference.

Example Usage

Remote URL

schemaValidator:
  id: schemav2validator
  config:
    type: url
    location: https://raw.githubusercontent.com/beckn/protocol-specifications/master/api/beckn-2.0.0.yaml
    cacheTTL: "7200"

Local File

schemaValidator:
  id: schemav2validator
  config:
    type: file
    location: ./validation-scripts/l2-config/mobility_1.1.0_openapi_3.1.yaml
    cacheTTL: "3600"

Dependencies

• github.com/getkin/kin-openapi - OpenAPI 3 parser and validator

Error Messages