The what and why of JSON(Schema)

JSONForms is an AngularJS-based framework to simplify the creation of forms for data entry and edit in web applications. It allows to declaratively define the content and layout of a form and to embed the form into your HTML with one simple <jsonforms> tag. If you would like to know more about JSONForms here is an introduction. Also the JSONForms homepage is a good starting point..

In this post we’ll first have a look at JSON schema: what it is, and what its applications are. We then illustrate how it relates to JSONForms and close with a small example demonstrating JSONForms.

What is JSONSchema?

While JSON is currently, undeniably, one of the most popular formats for exchanging data on the web, its meta-description JSONSchema isn’t yet as popular and widely known, but this is changing already.

In short, the main use of JSON schema is to describe the structure and validation constraints of your JSON documents. In contrast to XML, which allows you to create custom dialects, JSON is not as generalizable and flexible, however, it doesn’t want to be. JSON is meant to describe hierarchical data structures in a concise way, a task in which XML is generally considered to be less appropriate than JSON due to the verbose syntax.

A typical JSON schema for a user entity might look as follows:

user-schema.json

<pre lang="json">{
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string"
    },
    "lastName": {
      "type": "string"
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "gender": {
      "type": "string",
      "enum": ["Male", "Female"]
    },
    "active": {
      "type": "boolean"
    },
    "weight": {
      "type": "number"
    },
    "height": {
      "type": "integer"
    },
    "dateOfBirth": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": [ "firstName", "email" ],
  "additionalProperties": false
}
</pre>

Most of this should be self-explanatory: the user is an object with different properties where each one has a name and a type. The enum, format and required keywords are part of the Schema Validation specification:

  • enum expects an array of valid values
  • format describes a semantic validation constraint a value must fulfill. Other formats include email, hostname or ipv4
  • required lists all mandatory properties of a user, all others properties are optional

A valid instance that validates against this schema is given below:

<pre lang="json">{
  "firstName": "John",
  "email": "</pre>
<a href="mailto:jdoe@acme.org">jdoe@acme.org</a>
<pre lang="json">"
}
</pre>

At the time of writing (June 2015), the JSON schema standard isn’t yet finalized. The current specification is v4 and is split across different documents

The JSON Schema core

The core mainly defines terminology and describes common mechanisms such as URI resolutions scopes and dereferencing.

It also introduces the $schema keyword that identifies the used JSON Schema version and defines the application/schema+json application type.

All related specifications, like the Schema Validation and Hyper-Schema, use the terminology defined in the core.

Schema validation

The schema validation specification is one purpose of JSON Schema and describes different keywords that may be utilized to put constraints on JSON instances. In the context of strings, examples for such keywords are minLength and maxLength.

Hyper-Schema

The Hyper-Schema specification describes hyperlink- and hypermedia- related keywords that may be used with JSON Schema, such as links, ref and href keywords.

 

The purpose of these keywords is to provide a common way of defining hyper-text and hyper-media references, since JSON Schema does not provide a native way of handling those. All hyper-text and hyper-media references happen by using encoded strings. An example taken from the specification that uses the links keyword looks like this:

<pre lang="json">{
  "title": "Written Article",
  "type": "object",
  "properties": {
    "id": {
      "title": "Article Identifier",
      "type": "number"
    },
    "title": {
      "title": "Article Title",
      "type": "string"
    },
    "authorId": {
      "type": "integer"
    },
    "imgData": {
      "title": "Article Illustration (small)",
      "type": "string",
      "media": {
        "binaryEncoding": "base64",
        "type": "image/png"
      }
    }
  },
  "required" : ["id", "title", "authorId"],
  "links": [
    {
      "rel": "full",
      "href": "{id}"
    },
    {
      "rel": "author",
      "href": "/user?id={authorId}"
    }
  ]
}
</pre>

In the above example the links property is of special interest. It describes how the schema relates to valid instances. A link description consists of the rel and href keywords.

The value of the rel property indicates the name of the relation to the target resource while the href property is used as a template for a relative URI that can be used to obtain linked instance values.

In the above example this means if we would like to retrieve the author of an article, we would need to issue a (GET) request to the relative URI /user?id={authorId} where {authorId} will be replaced by the actual instance value.

The Hyper-Schema spec is likely to play a central role in JSONForms and we’ll come back to it in a future blog post.

Use in JSONForms

JSONForms, which we announced last week, relies heavily on the JSON and JSON Schema: for the description of your data it is making use of JSON schema while the UI schema is represented as regular JSON (for which we’ll define a schema later on).

For instance, if we’d like to model a widget that displays a user’s name as well as his/her height, we can do so by providing the following UI schema:

<pre lang="json">{
  "type": "HorizontalLayout",
  "elements": [
    {
      "type": "Control",
      "scope": {
        "$ref": "user-schema.json#/firstName"
      }
    },
    {
      "type": "Control",
      "scope": {
        "$ref": "user-schema.json#/gender"
      }
    }
  ]
}
</pre>

The type property in the above UI schema describes how child elements will be laid out. In the case of the HorizontalLayout, all elements will be put side-by-side in a row.

The “Control” type of the contained children describes a widget that is bound to a specific property of a JSON instance.

The wiring happens by specifying a reference via the $ref keyword. The value of the $ref property must be a URI and must adhere the JSON Pointer syntax. This URI needs to resolve to a valid JSON value. In our case, we assumed that the user schema has been saved to a file called user-schema.json file, therefore we first need to specify the actual schema we want to point at.  Note that it would also be possible of course, that the user schema is obtained by other means. After that, a JSON Pointer follows which, in our cases, retrieves the firstName and the gender property within the user schema, respectively.

The rendered result is quite unspectacular, but it illustrates the essence of having automatically rendered forms just by providing the UI schema and the schema:

image00

In case you want to play around with JSONForms you can already do so. We set-up a quick prototype for demo purposes, so you can get an impression of where JSONForms is heading.

If you would like to read more about JSONForms and how to get started with JSONForms, read on in the next blog post.

All feedback is appreciated, do not hesitate to contact us by Email, Twitter, Google+ or by commenting here!

Update: JSON Forms is now released regularly and a blog series on JSON Forms was just started introducing the features of JSON Forms based on one consistent example.

 

Foto
Guest Blog Post
Guest Author: Edgar Müller
4 Comments
  • Angelo
    Posted at 16:50, 2015-06-22

    Hi Edgar Müller,

    Many thanks for your article.

    I’m happy that you speak about JSON Schema because I need it for https://github.com/angelozerr/eclipse-wtp-json which is a JSON Editor for Eclipse IDE based on WTP :

    * to validate JSON.
    * to provides completion for JSON based on schema.

    My big problem is that I have not found a very good JSON Schema implementation for Java. It exists https://github.com/fge/json-schema-validator, but the big problem is that it is not able to support location error. In my case I need it, because I would like to highlight error from the JSON Schema validation.

    I have started a very basic implementation at https://github.com/angelozerr/eclipse-wtp-json/tree/master/core/org.eclipse.json/src/org/eclipse/json/impl/schema but if JSONForms provides a JSON Schema implementation which support location, it will fantastic.

    Thanks for your help.

    Regard’s Angelo

    • Edgar Müller
      Posted at 09:52, 2015-06-24

      Hi Angelo,
      JSONForms does not yet provide substantial support for validating JSON entities against some schema, but we are planning to do so in order to highlight errors when invalid data is entered by the user into any form.
      But since JSONForms is a Javascript-based framework it is very likely that we’ll use a library such as tv4 or is-my-json-valid to perform validation.
      Unfortunately I am not aware of any other Java library that performs JSON schema validation except the one you already mentioned.
      Regards,
      Edgar

  • Oswaldo Caballero
    Posted at 16:27, 2015-06-24

    Nice article. One question, however. In the example, even if the email field is declared as required, I don’t see it defined in the user-schema.json. Am I missing something?

    Thanks

    • Edgar Müller
      Posted at 09:50, 2015-06-26

      Hi Oswaldo, no, you didn’t miss anything, I simply forgot to include it in the schema. Fixed it. Thanks for the hint!