JSON-RPC Validator API Reference

Technical documentation for developers integrating JSON-RPC validation capabilities into their applications

On this page

Have questions?

Check out the interactive validator tool for examples and testing.

Try Validator Tool

Overview

The JSON-RPC Validator API provides programmatic access to validate JSON-RPC requests and responses against the official specification. It helps ensure your implementations conform to the JSON-RPC 1.0 or 2.0 standards, reducing errors and improving interoperability.

This client-side JavaScript library can be integrated into both browser and Node.js applications, allowing validation during development, testing, or in production environments.

Installation

The Validator API can be installed via npm:

npm install @jsonrpc-tools/validator

Or included via CDN:

<script src="https://cdn.jsonrpc.dev/validator/v1/validator.min.js"></script>

API Reference

Core Methods

validateRequest(request, options)

Validates a JSON-RPC request object against the specification.

Parameters:

  • request (Object|String): The JSON-RPC request to validate
  • options (Object, optional): Validation options

Returns:

A validation result object with valid boolean and errors array if invalid

validateResponse(response, options)

Validates a JSON-RPC response object against the specification.

Parameters:

  • response (Object|String): The JSON-RPC response to validate
  • options (Object, optional): Validation options

Returns:

A validation result object with valid boolean and errors array if invalid

validateBatch(batch, type, options)

Validates a batch of JSON-RPC requests or responses.

Parameters:

  • batch (Array|String): The JSON-RPC batch to validate
  • type (String): Either "request" or "response"
  • options (Object, optional): Validation options

Returns:

A validation result object with overall validity and individual results for each item

Request Validation

Request validation ensures that JSON-RPC requests meet the specification requirements.

Example: Validating a Request

// Import the validator
import { validateRequest } from '@jsonrpc-tools/validator';

// Define a JSON-RPC request
const request = {
  jsonrpc: "2.0",
  method: "subtract",
  params: [42, 23],
  id: 1
};

// Validate the request
const result = validateRequest(request);

if (result.valid) {
  console.log("Request is valid!");
} else {
  console.error("Validation errors:", result.errors);
}

Response Validation

Response validation ensures that JSON-RPC responses conform to the specification.

Example: Validating a Response

// Import the validator
import { validateResponse } from '@jsonrpc-tools/validator';

// Define a JSON-RPC response
const response = {
  jsonrpc: "2.0",
  result: 19,
  id: 1
};

// Validate the response
const result = validateResponse(response);

if (result.valid) {
  console.log("Response is valid!");
} else {
  console.error("Validation errors:", result.errors);
}

Batch Validation

The validator supports batch requests and responses as specified in JSON-RPC 2.0.

Example: Validating a Batch Request

// Import the validator
import { validateBatch } from '@jsonrpc-tools/validator';

// Define a JSON-RPC batch request
const batchRequest = [
  {
    jsonrpc: "2.0",
    method: "sum",
    params: [1, 2, 3],
    id: 1
  },
  {
    jsonrpc: "2.0",
    method: "subtract",
    params: [42, 23],
    id: 2
  }
];

// Validate the batch request
const result = validateBatch(batchRequest, "request");

console.log("Overall valid:", result.valid);
console.log("Individual results:", result.items);

Error Handling

Understanding error codes and messages from the validator.

Validation Error Structure
{
  valid: false,
  errors: [
    {
      code: "INVALID_FORMAT",
      message: "Request must include 'jsonrpc' property with value '2.0'",
      path: "jsonrpc"
    },
    // Additional errors...
  ]
}

Each error includes a code, descriptive message, and the path to the problematic property.

Common Error Codes

CodeDescription
INVALID_FORMATGeneral format issues
MISSING_PROPERTYRequired property is missing
INVALID_TYPEProperty has incorrect type
INVALID_VALUEProperty has invalid value
PARSE_ERRORFailed to parse JSON

Examples

Complete Usage Example

import { validateRequest, validateResponse } from '@jsonrpc-tools/validator';

// Function to process a JSON-RPC message
function processJsonRpc(message, isRequest = true) {
  try {
    // Parse the message if it's a string
    const data = typeof message === 'string' ? JSON.parse(message) : message;
    
    // Validate based on message type
    const result = isRequest 
      ? validateRequest(data, { version: '2.0', strictMode: true }) 
      : validateResponse(data, { version: '2.0' });
    
    if (!result.valid) {
      console.error('Validation failed:', result.errors);
      return {
        status: 'error',
        errors: result.errors
      };
    }
    
    // Process the valid message
    console.log(`Valid JSON-RPC ${isRequest ? 'request' : 'response'}`);
    return {
      status: 'success',
      data
    };
  } catch (error) {
    console.error('Processing error:', error);
    return {
      status: 'error',
      errors: [{ code: 'PROCESSING_ERROR', message: error.message }]
    };
  }
}

// Example usage
const validRequest = {
  jsonrpc: "2.0",
  method: "getUser",
  params: { id: 123 },
  id: 1
};

const invalidRequest = {
  method: "getUser",
  params: { id: 123 },
  id: 1
  // Missing jsonrpc field
};

console.log(processJsonRpc(validRequest));
console.log(processJsonRpc(invalidRequest));