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

Parameter	Type	Required	Default	Description
`type`	string	Yes	-	Type of spec source: "url" or "file" ("dir" reserved for future)
`location`	string	Yes	-	URL or file path to OpenAPI 3.1 spec
`cacheTTL`	string	No	"3600"	Cache TTL in seconds before reloading spec

How It Works

Load Spec: Loads OpenAPI spec from configured URL at startup
Extract Action: Extracts action from request context.action field
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
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
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

Request Action	Schema Enum	Match
`search`	`enum: ["search"]`	✅ Matches
`select`	`enum: ["select", "init"]`	✅ Matches
`discover`	`enum: ["search"]`	❌ No match
`on_search`	`enum: ["on_search"]`	✅ Matches

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

Scenario	Error Message
Action is number	`"failed to parse JSON payload: json: cannot unmarshal number into Go struct field .context.action of type string"`
Action is empty	`"missing field Action in context"`
Action not in spec	`"unsupported action: <action>"`
Invalid URL	`"Invalid URL or unreachable: <url>"`
Schema validation fails	Returns detailed field-level errors