543 - add : README file

2025-11-14 11:34:47 +05:30
parent 85e0f3c1cd
commit 9f913e6aa9
1 changed files with 130 additions and 0 deletions
--- a/pkg/plugin/implementation/schemav2validator/README.md
+++ b/pkg/plugin/implementation/schemav2validator/README.md
@@ -0,0 +1,130 @@
+# 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:
+    url: https://example.com/openapi-spec.yaml
+    cacheTTL: "3600"
+```
+
+### Configuration Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `url` | string | Yes | - | URL or file path to OpenAPI 3.1 specification |
+| `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
+
+### Local File
+
+```yaml
+schemaValidator:
+  id: schemav2validator
+  config:
+    url: ./validation-scripts/l2-config/mobility_1.1.0_openapi_3.1.yaml
+    cacheTTL: "3600"
+```
+
+### Remote URL
+
+```yaml
+schemaValidator:
+  id: schemav2validator
+  config:
+    url: https://raw.githubusercontent.com/beckn/protocol-specifications/master/api/beckn-2.0.0.yaml
+    cacheTTL: "7200"
+```
+
+## 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 |
+