139 lines
4.0 KiB
Markdown
139 lines
4.0 KiB
Markdown
# 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
|
|
|
|
```yaml
|
|
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
|
|
|
|
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
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```yaml
|
|
# 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
|
|
|
|
```yaml
|
|
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
|
|
|
|
```yaml
|
|
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 |
|
|
|