json-schema-agent

Please note this library is not ready for production use.

JSON Hyper-Schema HTTP REST client. Together with json-schema-core and json-schema-hyper, this library provides a basic mechanism for correlating instances with schema over HTTP. It also provides validation of request and response messages (schema and targetSchema), if json-schema-valid is used.

Refer to the JSON Schema Core v4 and Hyper-Schema IETF Internet Draft specs for more info.

Installation

component:

$ component install ericgj/json-schema-agent

npm:

$ npm install json-schema-agent-component

Examples

// Simple GET

var agent = new Agent();
agent.get('http://some.uri/path', function(err,correlation){
  correlation.instance  // the JSON instance (parsed body of response)
  correlation.schema    // the schema
})


// POST using link attributes

var link = { href: 'http://example.com/thing',
             rel: 'create',
             mediaType: 'application/vnd.thing+json'
           }

agent.post(link, obj, fn);

// or automatically follow method defined in link

link.method = 'POST'
agent.follow(link, obj, fn);


// follow chain of links

agent.follow(link, function(err, correlation){
  var nextItem = correlation.rel('next');  // find link rel="next" in the schema
  agent.follow(nextItem, fn)
})


// fetch and dereference schema from link
// note schema is cached to the agent

agent.getSchema(link, function(err,schema){
  schema    // the parsed, dereferenced schema
})


// dereference raw schema object

agent.dereference(data, function(err,schema){
  schema    // the parsed, dereferenced schema
})


// Configuration

// set default base uri for resolving relative URIs in links
// in-browser, typically you'd want to set this to window.location.origin

agent.base('http://example.com/api'); 


// set underlying http client (class)
var httpClient = require('superagent');
Agent.service(httpClient);

API

Running tests

In browser:

1. Unit tests:

• browse to file:// test/index.html
• browse to file:// test/refs.html

2. Functional tests:

$ node test/server.js

And browse to http://localhost:3000/functional.html

In Node-land:

1. Unit tests:

$ npm test

2. Functional tests:

$ node test/server.js &
$ mocha --ui bdd test/functional.js

Notes

• Note that an underlying HTTP client library must be specified, it is not built-in. The API for requests/responses is equivalent to a simple subset of superagent's. So superagent is the easiest choice, but not the only one.

• The Correlation object is implemented in json-schema-core, and extended in json-schema-hyper, qq.v. for more examples of usage.

• During dereferencing, missing fragment and external URI references yield errors.

• Missing schemas referenced (via HTTP headers) in instance data yield errors. However, if there are multiple indicated schemas, any that are not missing will be correlated to the instance data, in addition to yielding errors for the missing ones. (This behavior may change.)

• Cyclical references (i.e., schema A references schema B which references schema C, which in turn references schema A), are detected and yield an error.

Limitations

• Both Content-Type and Link header -style correlation methods are supported (see Core, sec. 8). However, specification of the root relation via the Link header (see Hyper-Schema, sec. 4.2), is not currently supported. This may be implemented in the future.

• This library provides parsing of the media property within schemas, however the internal representation of media type values (i.e., the use of this information in parsing the values) is left for the upstream application.

• The readOnly property within Link Description Object (LDO) schemas is not currently validated during write operations (POST/PUT/PATCH). It is not clear from the spec whether it is the responsibility of the client to do so.

• The pathStart schema property is not currently validated when correlating instances (Hyper-Schema, sec. 4.5). This may be implemented in the future.

• Likewise, the determination of authoritative representation of the self link target is not currently implemented (Hyper-Schema, sec. 5.2.2), but may be in the future.

License

MIT