limehee · limehee · Mar 3, 2026 · Mar 3, 2026 · Mar 3, 2026 · Mar 3, 2026
diff --git a/README.md b/README.md
@@ -9,6 +9,7 @@ Production-oriented JSON-RPC 2.0 server library for Java, with optional Spring W
 - Spring WebMVC transport adapter and Spring Boot auto-configuration
 - Multiple registration styles (annotation/manual/typed)
 - Explicit extension points (parser/validator/invoker/exception mapping/interceptors/metrics)
+- Response-side protocol utilities for bidirectional transports (classifier/parser/validator)
 - Focused dependency surface (no direct Guava, Commons Lang3, or Jakarta Validation dependency)
 
 ## Specification
@@ -20,7 +21,7 @@ Production-oriented JSON-RPC 2.0 server library for Java, with optional Spring W
 
 - Java: 17+
 - Spring Boot baseline: 4.0.3
-- Jackson baseline: 3.0.x
+- Jackson baseline: 3.1.x
 - Build: Gradle with Version Catalog
 - CI matrix: Java 17, 21, 25
 
@@ -174,6 +175,24 @@ Response:
 {"jsonrpc":"2.0","id":1,"result":"hello developer"}
 ```
 
+## Spring Configuration Example
+
+Use `jsonrpc.validation.request.*` and `jsonrpc.validation.response.*` for fine-grained validation control:
+
+```yaml
+jsonrpc:
+  validation:
+    request:
+      params-type-violation-code-policy: INVALID_REQUEST
+    response:
+      require-response-id-member: true
+      allow-fractional-response-id: false
+      allow-request-fields-in-response: false
+```
+
+For the full list of validation keys and defaults, see
+[`docs/configuration-reference.md`](docs/configuration-reference.md).
+
 ## Quick Start (Pure Java)
 
 ```java
@@ -256,11 +275,13 @@ Detailed docs are under [`docs/`](docs/):
 ## Sample
 
 - Spring Boot sample app: [`samples/spring-boot-demo`](samples/spring-boot-demo)
+- Pure Java sample app: [`samples/pure-java-demo`](samples/pure-java-demo)
 
 Run:
 
 ```bash
 ./gradlew -p samples/spring-boot-demo bootRun
+./gradlew -p samples/pure-java-demo run
 ```
 
 ## Project Docs

diff --git a/docs/architecture.md b/docs/architecture.md
@@ -43,6 +43,13 @@ flowchart LR
 
 Design goal: each concern is replaceable without rewriting the dispatcher.
 
+Response-side transport integrations can use these additional protocol components:
+
+- `JsonRpcEnvelopeClassifier`
+- `JsonRpcResponseParser`
+- `JsonRpcResponseValidator`
+- `JsonRpcResponseValidationOptions`
+
 ## 4. Registration Lifecycle in Auto-Configuration
 
 Method registration order in Spring Boot:
@@ -59,7 +66,7 @@ Protocol-level normalization:
 - parse error -> `-32700`
 - invalid request -> `-32600`
 - method not found -> `-32601`
-- invalid params -> `-32602`
+- invalid params -> default `-32602` (`params` type-violation code is configurable in `DefaultJsonRpcRequestValidator`)
 - unhandled exceptions -> `-32603`
 
 Transport-level status is handled separately by `JsonRpcHttpStatusStrategy`.

diff --git a/docs/configuration-reference.md b/docs/configuration-reference.md
@@ -4,23 +4,35 @@ All properties are under `jsonrpc.*` and are bound to `JsonRpcProperties`.
 
 ## 1. Property Table
 
-| Key                                           | Type                  | Default    | Description                                                     |
-|-----------------------------------------------|-----------------------|------------|-----------------------------------------------------------------|
-| `jsonrpc.enabled`                             | `boolean`             | `true`     | Enable/disable WebMVC endpoint auto-configuration               |
-| `jsonrpc.path`                                | `String`              | `/jsonrpc` | JSON-RPC HTTP endpoint path                                     |
-| `jsonrpc.max-batch-size`                      | `int`                 | `100`      | Maximum number of entries allowed in one batch request          |
-| `jsonrpc.max-request-bytes`                   | `int`                 | `1048576`  | Raw HTTP request payload size limit in bytes                    |
-| `jsonrpc.scan-annotated-methods`              | `boolean`             | `true`     | Scan Spring beans for `@JsonRpcMethod`                          |
-| `jsonrpc.include-error-data`                  | `boolean`             | `false`    | Include `JsonRpcException.data` in error responses              |
-| `jsonrpc.method-registration-conflict-policy` | `REJECT` or `REPLACE` | `REJECT`   | Duplicate method name registration policy                       |
-| `jsonrpc.method-allowlist`                    | `List<String>`        | `[]`       | Allowlist for method access filtering                           |
-| `jsonrpc.method-denylist`                     | `List<String>`        | `[]`       | Denylist for method access filtering (higher priority)          |
-| `jsonrpc.metrics-enabled`                     | `boolean`             | `true`     | Enable Micrometer interceptor/observer when registry is present |
-| `jsonrpc.metrics-latency-histogram-enabled`   | `boolean`             | `false`    | Publish latency histogram buckets                               |
-| `jsonrpc.metrics-latency-percentiles`         | `List<Double>`        | `[]`       | Optional latency percentiles (`0.0 < p < 1.0`)                  |
-| `jsonrpc.metrics-max-method-tag-values`       | `int`                 | `100`      | Max distinct method tag values before fallback to `other`       |
-| `jsonrpc.notification-executor-enabled`       | `boolean`             | `false`    | Enable executor-backed notification dispatch                    |
-| `jsonrpc.notification-executor-bean-name`     | `String`              | `""`       | Preferred executor bean name for notifications                  |
+| Key                                                    | Type                                  | Default          | Description                                                          |
+|--------------------------------------------------------|---------------------------------------|------------------|----------------------------------------------------------------------|
+| `jsonrpc.enabled`                                      | `boolean`                             | `true`           | Enable/disable WebMVC endpoint auto-configuration                    |
+| `jsonrpc.path`                                         | `String`                              | `/jsonrpc`       | JSON-RPC HTTP endpoint path                                          |
+| `jsonrpc.max-batch-size`                               | `int`                                 | `100`            | Maximum number of entries allowed in one batch request               |
+| `jsonrpc.max-request-bytes`                            | `int`                                 | `1048576`        | Raw HTTP request payload size limit in bytes                         |
+| `jsonrpc.scan-annotated-methods`                       | `boolean`                             | `true`           | Scan Spring beans for `@JsonRpcMethod`                               |
+| `jsonrpc.include-error-data`                           | `boolean`                             | `false`          | Include `JsonRpcException.data` in error responses                   |
+| `jsonrpc.validation.request.params-type-violation-code-policy` | `INVALID_PARAMS` or `INVALID_REQUEST` | `INVALID_PARAMS` | Error code used when `params` exists but is neither object nor array |
+| `jsonrpc.validation.response.require-json-rpc-version-20` | `boolean` | `true` | Require incoming response `jsonrpc` to equal `"2.0"` |
+| `jsonrpc.validation.response.require-response-id-member` | `boolean` | `true` | Require incoming responses to include an `id` member |
+| `jsonrpc.validation.response.allow-null-response-id` | `boolean` | `true` | Allow `id: null` in incoming responses |
+| `jsonrpc.validation.response.allow-string-response-id` | `boolean` | `true` | Allow string IDs in incoming responses |
+| `jsonrpc.validation.response.allow-numeric-response-id` | `boolean` | `true` | Allow numeric IDs in incoming responses |
+| `jsonrpc.validation.response.allow-fractional-response-id` | `boolean` | `true` | Allow fractional numeric IDs in incoming responses |
+| `jsonrpc.validation.response.require-exclusive-result-or-error` | `boolean` | `true` | Require exactly one of `result` or `error` |
+| `jsonrpc.validation.response.require-error-object-when-present` | `boolean` | `true` | Require `error` to be an object when present |
+| `jsonrpc.validation.response.require-integer-error-code` | `boolean` | `true` | Require `error.code` to be an integer |
+| `jsonrpc.validation.response.require-string-error-message` | `boolean` | `true` | Require `error.message` to be a string |
+| `jsonrpc.validation.response.allow-request-fields-in-response` | `boolean` | `true` | Allow request-only fields (`method`/`params`) on responses |
+| `jsonrpc.method-registration-conflict-policy`          | `REJECT` or `REPLACE`                 | `REJECT`         | Duplicate method name registration policy                            |
+| `jsonrpc.method-allowlist`                             | `List<String>`                        | `[]`             | Allowlist for method access filtering                                |
+| `jsonrpc.method-denylist`                              | `List<String>`                        | `[]`             | Denylist for method access filtering (higher priority)               |
+| `jsonrpc.metrics-enabled`                              | `boolean`                             | `true`           | Enable Micrometer interceptor/observer when registry is present      |
+| `jsonrpc.metrics-latency-histogram-enabled`            | `boolean`                             | `false`          | Publish latency histogram buckets                                    |
+| `jsonrpc.metrics-latency-percentiles`                  | `List<Double>`                        | `[]`             | Optional latency percentiles (`0.0 < p < 1.0`)                       |
+| `jsonrpc.metrics-max-method-tag-values`                | `int`                                 | `100`            | Max distinct method tag values before fallback to `other`            |
+| `jsonrpc.notification-executor-enabled`                | `boolean`                             | `false`          | Enable executor-backed notification dispatch                         |
+| `jsonrpc.notification-executor-bean-name`              | `String`                              | `""`             | Preferred executor bean name for notifications                       |
 
 ## 2. Validation Rules (Fail Fast)
 
@@ -36,6 +48,10 @@ Startup fails with `IllegalArgumentException` when any of these conditions occur
 - `jsonrpc.metrics-latency-percentiles` is null
 - any percentile is null, `<= 0.0`, or `>= 1.0`
 - `jsonrpc.notification-executor-bean-name` is null
+- `jsonrpc.validation` is null
+- `jsonrpc.validation.request` is null
+- `jsonrpc.validation.request.params-type-violation-code-policy` is null
+- `jsonrpc.validation.response` is null
 - allowlist/denylist list itself is null
 - allowlist/denylist contains null or blank values
 
@@ -86,6 +102,7 @@ Example environment variable mapping:
 
 - `jsonrpc.max-request-bytes` -> `JSONRPC_MAX_REQUEST_BYTES`
 - `jsonrpc.method-registration-conflict-policy` -> `JSONRPC_METHOD_REGISTRATION_CONFLICT_POLICY`
+- `jsonrpc.validation.request.params-type-violation-code-policy` -> `JSONRPC_VALIDATION_REQUEST_PARAMS_TYPE_VIOLATION_CODE_POLICY`
 
 ## 5. Example Configurations
 
@@ -99,6 +116,21 @@ jsonrpc:
   method-registration-conflict-policy: REJECT
   scan-annotated-methods: true
   include-error-data: false
+  validation:
+    request:
+      params-type-violation-code-policy: INVALID_PARAMS
+    response:
+      require-json-rpc-version-20: true
+      require-response-id-member: true
+      allow-null-response-id: true
+      allow-string-response-id: true
+      allow-numeric-response-id: true
+      allow-fractional-response-id: true
+      require-exclusive-result-or-error: true
+      require-error-object-when-present: true
+      require-integer-error-code: true
+      require-string-error-message: true
+      allow-request-fields-in-response: true
   method-allowlist: []
   method-denylist: []
 ```
@@ -139,7 +171,7 @@ The project ships Spring Boot configuration metadata via:
 This enables:
 
 - property key completion
-- enum value suggestions (`REJECT`, `REPLACE`)
+- enum value suggestions (`REJECT`, `REPLACE`, `INVALID_PARAMS`, `INVALID_REQUEST`)
 - metadata hints in IntelliJ and Spring-aware tooling
 
 ## 7. Related References

diff --git a/docs/extension-points.md b/docs/extension-points.md
@@ -14,6 +14,26 @@ You can override any of these with custom Spring beans:
 - `JsonRpcResponseComposer`
 - `JsonRpcNotificationExecutor`
 
+Response-side interfaces are available in `jsonrpc-core` for transport integrations:
+
+- `JsonRpcEnvelopeClassifier`
+- `JsonRpcResponseParser`
+- `JsonRpcResponseValidator`
+- `JsonRpcResponseValidationOptions`
+
+Spring Boot auto-configuration currently wires request-dispatch components by default. For response-side
+processing, create and use these components explicitly in your transport adapter.
+
+Request validator customization example:
+
+- Spring Boot property `jsonrpc.validation.request.params-type-violation-code-policy=INVALID_PARAMS`
+  keeps default `-32602` for `params` type violations.
+- Spring Boot property `jsonrpc.validation.request.params-type-violation-code-policy=INVALID_REQUEST`
+  maps the same violation to `-32600`.
+- For non-Spring or fully custom logic, you can still construct
+  `DefaultJsonRpcRequestValidator(JsonRpcParamsTypeViolationCodePolicy.INVALID_PARAMS)` or
+  `DefaultJsonRpcRequestValidator(JsonRpcParamsTypeViolationCodePolicy.INVALID_REQUEST)` directly.
+
 ## 2. Interceptor Chain
 
 `JsonRpcInterceptor` hooks:

diff --git a/docs/index.md b/docs/index.md
@@ -11,6 +11,7 @@
 ## 2. Core Reference
 
 - Protocol behavior and JSON-RPC compliance: [`protocol-and-compliance.md`](protocol-and-compliance.md)
+- Incoming response classification/parsing/validation guidance: [`protocol-and-compliance.md`](protocol-and-compliance.md), [`pure-java-guide.md`](pure-java-guide.md)
 - Registration styles and parameter binding rules: [`registration-and-binding.md`](registration-and-binding.md)
 - Configuration keys, defaults, constraints, and precedence: [`configuration-reference.md`](configuration-reference.md)
 - Extension interfaces and override points: [`extension-points.md`](extension-points.md)