JSON-RPC Version Differences
Understand the key differences between JSON-RPC 1.0 and 2.0
On this page
Overview
JSON-RPC has evolved through two major versions: 1.0 and 2.0. While both serve the same fundamental purpose of providing a lightweight remote procedure call protocol using JSON, version 2.0 introduced several important improvements and changes.
This reference guide highlights the key differences between the two versions to help you understand the evolution of the protocol and make informed decisions when implementing or migrating JSON-RPC services.
Key Differences at a Glance
| Feature | JSON-RPC 1.0 | JSON-RPC 2.0 |
|---|---|---|
| Version identifier | Not required | Required ("jsonrpc": "2.0") |
| Parameter structure | Array only | Array or Object |
| Notification support | Basic | Explicit (null id) |
| Batch requests | Not specified | Supported |
| Error objects | Simple | Structured with codes |
| ID data types | No restrictions | String, Number, or null |
Request Format Differences
The structure of JSON-RPC requests evolved significantly between versions 1.0 and 2.0:
JSON-RPC 1.0 Request
{
"method": "subtract",
"params": [42, 23],
"id": 1
}- No version identifier - Version is implied
- Positional parameters only - Parameters must be in an array
- ID field - Can be any type, not just strings or numbers
JSON-RPC 2.0 Request
{
"jsonrpc": "2.0",
"method": "subtract",
"params": {"minuend": 42, "subtrahend": 23},
"id": 1
}- Required version identifier -
"jsonrpc": "2.0" - Named or positional parameters - Can use object or array
- Restricted ID types - Must be string, number, or null
Key Enhancement: The ability to use named parameters in version 2.0 significantly improves readability and allows for optional parameters to be more easily implemented.
Response Format Differences
Response formats also changed substantially between JSON-RPC 1.0 and 2.0:
Successful Responses
JSON-RPC 1.0 Response
{
"result": 19,
"error": null,
"id": 1
}- Both result and error fields - Error is null for success
- No version identifier - Version is implied
- ID matching request - Used for correlation
JSON-RPC 2.0 Response
{
"jsonrpc": "2.0",
"result": 19,
"id": 1
}- Result field only - Error field is omitted for success
- Required version identifier -
"jsonrpc": "2.0" - ID matching request - Same as 1.0
Error Responses
JSON-RPC 1.0 Error
{
"result": null,
"error": "Method not found",
"id": 1
}- Simple error field - Usually a string message
- Result is null - For error responses
- No standardized error codes - Implementation-dependent
JSON-RPC 2.0 Error
{
"jsonrpc": "2.0",
"error": {
"code": -32601,
"message": "Method not found",
"data": "The method 'subtractX' does not exist"
},
"id": 1
}- Structured error object - With code, message, and optional data
- No result field - Omitted for error responses
- Standardized error codes - Predefined ranges for different error types
Error Handling Improvements
One of the most significant improvements in JSON-RPC 2.0 is the structured error handling system:
Standardized Error Codes
| Error Code | Message | Meaning |
|---|---|---|
| -32700 | Parse error | Invalid JSON was received |
| -32600 | Invalid Request | The JSON sent is not a valid Request object |
| -32601 | Method not found | The method does not exist / is not available |
| -32602 | Invalid params | Invalid method parameters |
| -32603 | Internal error | Internal JSON-RPC error |
| -32000 to -32099 | Server error | Reserved for implementation-defined server errors |
Error Object Structure
In JSON-RPC 2.0, error objects have a standardized structure:
{
"code": -32601, // Required: Error code
"message": "Method not found", // Required: Short description
"data": "Additional details" // Optional: Extra information
}The optional data field can contain any additional information about the error, which is particularly useful for debugging or providing more context to the client.
Batch Processing
JSON-RPC 2.0 introduced formal support for batch processing, allowing multiple requests to be sent in a single call:
Batch Request Example
[
{"jsonrpc": "2.0", "method": "sum", "params": [1,2,4], "id": "1"},
{"jsonrpc": "2.0", "method": "notify_hello", "params": [7]},
{"jsonrpc": "2.0", "method": "subtract", "params": [42,23], "id": "2"},
{"foo": "boo"},
{"jsonrpc": "2.0", "method": "foo.get", "params": {"name": "myself"}, "id": "5"}
]Batch Response Example
[
{"jsonrpc": "2.0", "result": 7, "id": "1"},
{"jsonrpc": "2.0", "result": 19, "id": "2"},
{"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null},
{"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found"}, "id": "5"}
]Key Points:
- Notifications in a batch (requests without an ID) receive no response
- Responses come in any order, not necessarily matching the request order
- Matching between requests and responses is done via the ID field
- If the batch itself is invalid JSON, a single error response is returned (not an array)
Notifications
Both JSON-RPC 1.0 and 2.0 support notifications, but the implementation differs:
JSON-RPC 1.0 Notification
{
"method": "update",
"params": [1, 2, 3, 4, 5],
"id": null
}- ID field is null - Indicates no response is needed
- Not explicitly defined - Behavior varies across implementations
JSON-RPC 2.0 Notification
{
"jsonrpc": "2.0",
"method": "update",
"params": [1, 2, 3, 4, 5]
}- No ID field - Explicitly omitted (not null)
- Formally defined - Clear specification of behavior
- No response - Server must not reply, even on error
Key Difference: In JSON-RPC 2.0, notifications are explicitly identified by the absence of an ID field, not by setting the ID to null. This makes the protocol more precise and avoids potential ambiguity.
Common Use Cases for Notifications
- Event broadcasting (e.g., "user.loggedIn", "system.shutdown")
- Logging information that doesn't require a response
- One-way status updates that don't need confirmation
- Performance optimization when response handling is unnecessary
Migration Guide: 1.0 to 2.0
If you're upgrading from JSON-RPC 1.0 to 2.0, follow these steps to ensure compatibility:
1. Add the version field
Add the "jsonrpc": "2.0" field to all request and response objects.
Before:
{
"method": "subtract",
"params": [42, 23],
"id": 1
}After:
{
"jsonrpc": "2.0",
"method": "subtract",
"params": [42, 23],
"id": 1
}2. Update response structure
For success responses, remove the error field. For error responses, remove the result field.
Before (success):
{
"result": 19,
"error": null,
"id": 1
}After (success):
{
"jsonrpc": "2.0",
"result": 19,
"id": 1
}3. Restructure error responses
Convert simple error fields to structured error objects with code, message, and optional data.
Before:
{
"result": null,
"error": "Method not found",
"id": 1
}After:
{
"jsonrpc": "2.0",
"error": {
"code": -32601,
"message": "Method not found"
},
"id": 1
}4. Update notification format
Change notifications to completely omit the ID field rather than setting it to null.
Before:
{
"method": "update",
"params": [1,2,3,4,5],
"id": null
}After:
{
"jsonrpc": "2.0",
"method": "update",
"params": [1,2,3,4,5]
}5. Implement named parameters (optional)
Consider switching from positional parameters to named parameters for better readability.
Before:
{
"method": "subtract",
"params": [42, 23],
"id": 1
}After:
{
"jsonrpc": "2.0",
"method": "subtract",
"params": {
"minuend": 42,
"subtrahend": 23
},
"id": 1
}Server-Side Considerations
- Update error handling to use standardized error codes
- Add version detection to support both protocol versions during transition
- Implement batch processing if not already supported
- Update validation logic to check for the required "jsonrpc" field
- Add support for both positional and named parameters
Backward Compatibility: If you need to maintain compatibility with existing clients, consider implementing a dual-mode server that can detect and respond to both JSON-RPC 1.0 and 2.0 requests. This allows for a gradual transition of client applications.