jrpc-schema

Parses a json schema into a simple usable api object

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 socket = new WebSocket('ws://localhost/');

The main "meat" of the library. The Schema constructor should be invoked with a JSON Schema object (not a JSON string);

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).

Schema

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

Usage

var root = parse(schema)
 
//Returns true if `value` is an object 
root.schema(value)
 
//Returns true if `value` is a string 
root.schema.name(value)
 
//Returns true if `value` is an integer larger then 125 
root.schema.age(value)

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.

Schema

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"
            }
        ]
    }
}

Usage

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

JSON RPC notifications are treated similarly to methods.

Schema

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

Usage

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

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) {
    console.log(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.