2.1.0 • Public • Published

Parse JSON-Schemas with support for JSON-RPC Service Descriptors

This module allows you to parse a json schema and then provides you an object to validate a javascript value against. In addition it supplies a simple way to call JSON-RPC methods and subscribe to notifications described by this spec: http://www.simple-is-better.org/json-rpc/jsonrpc20-schema-service-descriptor.html


This library is not bound to a specific method for transmitting data back and forth between your app and the queried server. Therefore you have to provide the facilities for this on your own. For all examples below, we use a WebSocket instance:

var jrpc = require('jrpc-schema');
var Schema = jrpc.Schema;
var socket = new WebSocket('ws://localhost/');


jrpc.Schema(schemaObject, transmitterFunction)

The main "meat" of the library. The Schema constructor should be invoked with a JSON Schema object (not a JSON string). The second parameter should be a transmitter function, which takes a json string as its first argument and sends it to the server.

var schema = new jrpc.Schema(someSchema, socket.send.bind(socket));

You will then have to pass your servers responses into the schemas handleResponse method:

socket.on('message', schema.handleResponse.bind(schema));

Handling errors

To handle any errors while e.g. parsing JSON, you can attach a handler to the schema object:

schema.onerror = e => console.error(e);

If no handler is attached, the error will be thrown.

Validator Functions

A validator function is a function, which takes a javascript value and validates it against a specific schema. It simply returns true if the value is valid and false otherwise. In addition, if the validators schema had any other schemas assigned to it as properties (this will be the case for almost all top-level json-schemas), it has a validator function for each of those sub-schemas assigned to it as a property (as functions are objects in js).


var schema = {
    "name": {
        "type": "string"
    "age" :{
        "type": "integer",
        "maximum": 125


var root = new Schema(schema, someTransmitter);
//Returns true if `value` is an object
//Returns true if `value` is a string
//Returns true if `value` is an integer larger then 125

RSON-RPC Methods

If a json-schema describes a JSON-RPC method, we do not create a validator function. Instead we generate a wrapper for that method. This wrapper takes arguments either by order as an array, or as one object by name. The method will return a promise, which will be fulfilled with the methods return value once it becomes available.


var schema = {
    "square": {
        "type": "method",
        "returns": "number",
        "params": [
                "type": "number",
                "name": "square",
                "required": true,
                "minimum": 0,
                "description": "Number to find the square root of"
             "type": "number",
             "name": "nth",
             "default": 2
             "minimum": 2,
             "description": "The degree of the root"


var root = new Schema(schema, someTransmitter);
    square: 27,
    nth: 3
}).then(function(result) {
    //Result should be 3, given a sane server
//By order
root.schema.square(27, 3).then(function(result) {
Batch Requests

If you need to send multiple requests in a batch, you can use a batch object:

var root = new Schema(schema, transmitter);
var batch = root.batch();
var res = batch.schema.someMethod();
var res2 = batch.schema.someOtherMethod();

The batch object will have all the methods of the main schema. But they will all be queued until you call .send() on the batch object.

The methods still return promises which will be resolved with the methods result.

JSON-RPC Notifications

JSON RPC notifications are treated similarly to methods.


var schema = {
    "notify": {
        "params": [
                "name": "data",
                "required": true,
                "type": number
        "returns": null,
        "type": "notification"


var root = new Schema(schema, someTransmitter);
//May be called multiple times
root.schema.notify(function(data) {
//Alternative without the need to have been defined in the schema
root.notifications.on('notify', function(data) {

jrpc.run(method, params, transmitter)

Call a single json-rpc method and return a Promise. method should be the method name, params should be a parameter object and the transmitter should be a function which takes a json string as its only argument. This string should then be send to the server.

The returned Promise has a .handle(json) which you should call with all of your servers responses. The promise will then be resolved with the correct value as soon as it is available.

//Run the request
var playerInfo = jrpc.run('Player.GetInfo', {
    'playerid': 1
}, socket.send.bind(socket));
//Log the result
playerInfo.then(function(info) {
//Ensure the library gets the servers data
socket.on('message', playerInfo.handle);

As you can see, this is slightly convoluted and does not utilize json-schemas at all. You should use an instance of jrpc.Schema wherever possible.




Package Sidebar


npm i jrpc-schema

Weekly Downloads






Last publish


  • paulavery