Jsonary

The JSON client library

Download

Download the quick-start bundle.

What is Jsonary?

Jsonary can present JSON data as hyper-text, using JSON Hyper-Schema.

JSON Hyper-Schemas turn your existing data into hyper-text - no special structures, no reserved properties. The purpose of Jsonary is to combine JSON data with hyper-schemas, in order to treat it as hyper-text.

Jsonary can follow the hyper-links in your data, present an interface for forms, and can get you a working client with almost no effort if your API uses JSON Hyper-Schema.

The UI can be customised piece-by-piece, turning your generic client into a production interface. See this page for more information about Jsonary.

Getting started

First, download this bundle - it contains a generic JSON browser, and the default set of renderers.

Then follow this step-by-step guide to start using JSON Hyper-Schema with your API.

What is JSON Schema?

JSON Schema documents describe the nature and shape of JSON data. They can also specify how to infer hyperlinks, turning JSON data into hyper-media documents. The main site is json-schema.org.

{
	"title": "Example schema",
	"type": "object",
	"properties": {
		"id": {"type": "integer"},
		"authorId": {"type": "integer"},
		"message": {"type": "string"}
	},
	"links": [
		{"rel": "self", "href": "/posts/{id}"},
		{"rel": "author", "href": "/users/{authorId}"}
	]
}

This page provides some documentation for the format, along with interactive examples for various keywords.

Why do we use it?

JSON Schemas can provide constraints on the data (e.g. data types, required properties, minimum lengths), which Jsonary can use to provide a default editing interface. Hyper-schemas also enable us to treat JSON data as hyper-media, giving us links and HTML-form-style functionality.

Schemas can reference/link to other schemas, and specify complex behaviours - for example, conditional schemas that only apply if a particular property is present, or lists of sub-schemas of which only one may apply. However, each schema has a unique URI, so the are perfect for selecting custom renderers.

Documentation and walkthroughs

There are some walkthroughs, that show some use cases for Jsonary:

The raw API documentation is still being improved. You can view the current state of it here.

Plugins/Extensions

Jsonary can be extended to provide additional functionality, either globally or to Jsonary Data/Schema objects.

Here are the plugins that are bundled with Jsonary:

Tests

There are some tests for Jsonary.

License

Jsonary is licensed under the MIT License.