JSON Schema Reference

The complete guide to JSON Schema definitions for JSON-RPC protocols

On this page

Try our validator

Validate your JSON-RPC messages using our schema validator.

Try Validator

JSON Schema for JSON-RPC

JSON Schema provides a powerful way to define the structure of JSON-RPC requests and responses. This reference documents the standard schemas for JSON-RPC 2.0 messages, which can be used for validation, documentation, and code generation.

Using JSON Schema with JSON-RPC provides several benefits:

  • Automated validation of requests and responses
  • Clear documentation of expected message formats
  • Type checking and code completion in compatible IDEs
  • Automated code generation for clients and servers

JSON-RPC Request Schema

The standard schema for a JSON-RPC 2.0 request:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "JSON-RPC 2.0 Request",
  "description": "A JSON-RPC 2.0 request object",
  "type": "object",
  "required": ["jsonrpc", "method"],
  "properties": {
    "jsonrpc": {
      "type": "string",
      "enum": ["2.0"],
      "description": "JSON-RPC version string"
    },
    "method": {
      "type": "string",
      "description": "The name of the method to be invoked"
    },
    "params": {
      "description": "Parameter values to be used during the invocation of the method",
      "oneOf": [
        {
          "type": "array",
          "description": "Positional parameters"
        },
        {
          "type": "object",
          "description": "Named parameters"
        }
      ]
    },
    "id": {
      "description": "Identifier established by the client",
      "oneOf": [
        { "type": "string" },
        { "type": "number" },
        { "type": "null" }
      ]
    }
  },
  "additionalProperties": false
}

Example Valid Request

{
  "jsonrpc": "2.0",
  "method": "user.get",
  "params": {
    "userId": 123
  },
  "id": "req-1"
}

JSON-RPC Response Schema

The standard schema for a JSON-RPC 2.0 response:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "JSON-RPC 2.0 Response",
  "description": "A JSON-RPC 2.0 response object",
  "type": "object",
  "required": ["jsonrpc"],
  "properties": {
    "jsonrpc": {
      "type": "string",
      "enum": ["2.0"],
      "description": "JSON-RPC version string"
    },
    "result": {
      "description": "The result of the RPC call if successful"
    },
    "error": {
      "description": "Error information if an error occurred",
      "$ref": "#/definitions/error"
    },
    "id": {
      "description": "Identifier matching the request",
      "oneOf": [
        { "type": "string" },
        { "type": "number" },
        { "type": "null" }
      ]
    }
  },
  "oneOf": [
    { "required": ["result", "id"] },
    { "required": ["error", "id"] }
  ],
  "additionalProperties": false,
  "definitions": {
    "error": {
      "type": "object",
      "required": ["code", "message"],
      "properties": {
        "code": {
          "type": "integer",
          "description": "Error code"
        },
        "message": {
          "type": "string",
          "description": "Error message"
        },
        "data": {
          "description": "Additional error information"
        }
      },
      "additionalProperties": false
    }
  }
}

Example Success Response

{
  "jsonrpc": "2.0",
  "result": {
    "id": 123,
    "name": "John Doe",
    "email": "[email protected]"
  },
  "id": "req-1"
}

Error Object Schema

The schema for the error object within a JSON-RPC 2.0 response:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "JSON-RPC 2.0 Error Object",
  "description": "Error object in a JSON-RPC 2.0 response",
  "type": "object",
  "required": ["code", "message"],
  "properties": {
    "code": {
      "type": "integer",
      "description": "Error code",
      "examples": [-32700, -32600, -32601, -32602, -32603]
    },
    "message": {
      "type": "string",
      "description": "Error message",
      "examples": ["Parse error", "Invalid Request", "Method not found"]
    },
    "data": {
      "description": "Additional error information that may assist in debugging"
    }
  },
  "additionalProperties": false
}

Example Error Response

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32601,
    "message": "Method not found",
    "data": "The method 'user.delete' does not exist"
  },
  "id": "req-1"
}

Custom Method Schemas

Beyond the core protocol schemas, you can define schemas for specific RPC methods:

Method-Specific Request Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "User.Create Request",
  "description": "Request schema for the user.create method",
  "type": "object",
  "required": ["jsonrpc", "method", "params", "id"],
  "properties": {
    "jsonrpc": { "enum": ["2.0"] },
    "method": { "enum": ["user.create"] },
    "id": {},
    "params": {
      "type": "object",
      "required": ["name", "email"],
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        "email": {
          "type": "string",
          "format": "email"
        },
        "role": {
          "type": "string",
          "enum": ["admin", "user", "guest"],
          "default": "user"
        }
      },
      "additionalProperties": false
    }
  }
}

Method-Specific Response Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "User.Create Response",
  "description": "Response schema for the user.create method",
  "type": "object",
  "required": ["jsonrpc", "result", "id"],
  "properties": {
    "jsonrpc": { "enum": ["2.0"] },
    "id": {},
    "result": {
      "type": "object",
      "required": ["id", "name", "email", "created"],
      "properties": {
        "id": {
          "type": "integer",
          "description": "Unique user ID generated by the system"
        },
        "name": { "type": "string" },
        "email": { "type": "string" },
        "role": { "type": "string" },
        "created": {
          "type": "string",
          "format": "date-time"
        }
      }
    }
  }
}

Using Schemas for Validation

You can use these schemas with JSON Schema validators to ensure protocol compliance:

JavaScript Validation Example

// Using Ajv for JSON Schema validation
const Ajv = require('ajv');
const ajv = new Ajv();

// Load the JSON-RPC request schema
const requestSchema = require('./schemas/jsonrpc-request.json');
const validate = ajv.compile(requestSchema);

function validateJsonRpcRequest(request) {
  const valid = validate(request);
  if (!valid) {
    console.error('Invalid JSON-RPC request:', validate.errors);
    return false;
  }
  return true;
}

// Example usage
const request = {
  jsonrpc: '2.0',
  method: 'user.get',
  params: { userId: 123 },
  id: 'req-1'
};

if (validateJsonRpcRequest(request)) {
  console.log('Request is valid');
  // Process the request
} else {
  console.log('Request is invalid');
  // Return an error response
}

Tip: Consider using OpenAPI/Swagger to document your JSON-RPC API using these schemas. This allows you to generate interactive documentation and client libraries.