Home > Computer Sciences > JSON Schema: first Java implementation available!

JSON Schema: first Java implementation available!

Java source code available on gitorious

Yesterday night, I published a first version of the source code on Gitorious. It is released under the Apache V2.0 License.

This implementation covers nearly all of the “Core Schema Definition” corresponding to the paragraph 5 of the specification.  The “missing” items (mainly, 5.21, 5.22 and 5.25) concern points of the specifications that need to be clarified in order to be implemented.

Concerning the implementation itself, the main design ideas are the following:

  • Each validator should be a small stateless and easy to test object, implementing one and only one of the rules of the specification.
  • A schema object should be a “validating engine”,  containing a graph of validator objects built on construction.
  • Once loaded a schema object should be reusable in order to validate as many JSON instances as needed.

As you may already have guessed, a “wide” set of JUnit test cases is provided with the source code. Each test case, allows to test one of the “validators” separately using very simple JSON schemas and instances. There is also a more “complicated” and “complete” test case allowing to test combinations of validators.

Finally, some more work has to be done on the Java Documentation … I will cope with it during the following days and push it to the central repository.


The following few lines of code, show you how you can use the implementation in order to validate an JSON instance against a JSON schema:

		// Jackson parsing API: the ObjectMapper can be provided
		// and configured differently depending on the application
		ObjectMapper mapper = new ObjectMapper();

		// Allows to retrieve a JSONSchema object on various sources
		// supported by the ObjectMapper provided
		JSONSchemaProvider schemaProvider = new JacksonSchemaProvider(mapper);

		// Retrieves a JSON Schema object based on a file
		InputStream schemaIS = new FileInputStream("schema.json");
		JSONSchema schema = schemaProvider.getSchema(schemaIS);

		// Validates a JSON Instance object stored in a file
		InputStream instanceIS = new FileInputStream("instance1.json");
		List<String> errors = schema.validate(instanceIS);

		// Display the eventual errors
		for ( String s : errors ) {

The project should be easy to build with Maven: a “pom.xml” file is provided with the source code. A simple “mvn package” should be enough to build the code, run the tests, produce the javadoc and the jar file.

I have also made some JAR’s available for those, who do not wish to build the JSON Schema validator from the source code:

  • The binary archive is available here
  • The javadoc archive is available here

Plans for the near future …

I will post on the Jackson project’s mailing lists in order to get some feedback from them: I would be very happy and proud to see this code tightly integrated inside the Jackson project!

I will also ask for the needed precisions concerning the “missing” points of this implementation to the people in charge of the specification: I would love to have 100% of the specification implemented. More generally, I have some questions concerning the possibility to reference / reuse existing JSON Schemas: the Core Schema Definition seems to allow only “anonymous” types. In a complex schema, the possibility to define and reuse “named” types (like in XML Schema) would be very handy.

At this very early stage, any help will be welcome: testing, using, fixing, extending … there is still some work to be done before the first release. I plan to use this implementation as it is on a project in the very near future … I will of course publish any fix, extension, documentation. For example, I will make a Google Guice module in the context of this project in order to avoid all the “boiler plate” instantiation code that you can see in my example (Google Guice is my preferred choice when it comes to DI 😉 ).

Implementation Matrix: Paragraph 5 – Core Schema Definition

$ Title Status
5.1 type simple: OK / union: OK
5.2 properties OK
5.3 items simple: OK / tuple: OK
5.4 optional OK
5.5 additionalProperties OK
5.6 requires name: OK / schema: OK
5.7 minimum OK
5.8 maximum OK
5.9 minimumCanEqual OK
5.10 maximumCanEqual OK
5.11 minItems OK
5.12 maxItems OK
5.13 uniqueItems OK
5.14 pattern OK
5.15 maxLength OK
5.16 minLength OK
5.17 enum OK
5.18 title NOTHING
5.19 description NOTHING
5.20 format TODO (OPTIONAL)
5.21 contentEncoding TODO
5.22 default TODO
5.23 divisibleBy OK
5.24 disallow OK
5.25 extends TODO
  1. May 18, 2010 at 03:27

    Very cool!

    I agree in that ability to reference other schema components is a must for real production schemas, to support modularity and ability to reuse types and even type libraries.

  2. Noel
    August 13, 2010 at 15:41

    First of all I want to say congratulations and thanks for providing such a useful tool! I have a situation: I have a JSON field that can be either an object or an array of those objects and can validate this using “type”: [“object”, “array”]. However I want to validate the contents of the object, of array of objects. Is this possible?

    If there’s a more appropriate forum for me to ask these questions, please let me know 😉

    Thanks once again!

    • August 23, 2010 at 13:45

      Sorry for the delay of the response, I was on holidays 🙂

      There’s a very simple way to do what you want. You can specify a union type as you did and then use the “properties” and the “items” attributes to specify the contents of your object and array respectively.

      The following JSON Schema illustrates this idea:
      “description”: “A test schema specifying an array or an object”,
      “type”: [“object”, “array”],
      “properties”: {
      “p1”: {“type”: “string”},
      “p2”: {
      “type”: “integer”,
      “minimum”: 5,
      “maximum” : 10,
      “additionalProperties”: false
      “items” : {
      “type” : “string”,
      “maxLength” : 3

      The 2 following JSON structures will be valid against this schema:
      [“abc”, “def”]

      { “p1” : “test object”, “p2” : 5 }

      Hope this helps !

  3. Noel
    August 23, 2010 at 14:25

    Cool, thanks Nico 😀

  4. Joe
    September 20, 2010 at 17:59

    Hi Nic, what’s the status of your Gitorious project now? Are you likely to be continuing with development in future?

    I’m also interested to know if you have produced a releases yet, I guess there’s nothing stopping me adding my own build into our local Maven repository but it would be good if you had maybe one (early) build available.

    I’m also interested to know if you have seen or are familiar with this project:

    Maybe efforts could be combined?

    • September 20, 2010 at 20:57


      thanks for your interest 🙂

      I have been quite busy these days (I am currently moving from Greece to France) but I will definitely continue this implementation. Please give me one more week … 🙂

      Moreover, I have been following the JSON Schema specification very closely … there is a lot going on on this side too. However, I still have some doubts / questions / problems on the “referencing” part of the spec.

      Anyway, help is of course welcome, you can clone the git repository and then request that I merge your changes to the main repository.

      Concerning the jsontools project that you mentioned, last time I looked they were not implementing the JSON Schema specification (i.e. they were using another schema language) … but that was some time ago.

      Thanks again !

  5. Joe
    October 27, 2010 at 13:44

    Hi Nico,

    First – great work on the project so far! We need to start validating JSON output during our acceptance tests and it’s really good to see real progress on a Java implementation.

    I have a couple of questions:

    – Are you close to creating an initial release (alpha/beta?). You mention in your post that you’re very near to using the implementation as it stands in a real project – would now be a good time to create some binaries?

    – Has the implementation matrix changed at all in the last few months? If we start using this library I’d be interested to get the latest information on exactly what JSON schema features we can use.

    – Do you have any thoughts about what are the most important/pressing features that are not yet implemented?

  6. Joe
    October 27, 2010 at 13:56

    Apologies, I’ve just found the current implementation matrix @ src/test/resources/status.txt

  7. Joe
    November 1, 2010 at 13:50

    Hi Nick,
    Any chance you could maybe spin-up a google code project for this? Seems like a good time to start a project page (and an issue tracker).

    I’d like to contribute to the project if I can. What do you need?

  8. November 1, 2010 at 22:21


    sorry again for the delay … it is taking me far more time to move to Paris than I expected … and I am not done yet!

    Anyway, here are my plans for the JSON Schema implementation:

    1) Review the 3rd revision of the JSON Schema specification and implement the changes
    2) Implement the reference mechanism : this is by far the most urgent thing to do
    3) Enrich the javadoc
    4) Release a first version of the implementation
    5) Enrich the Project page and the wiki page on gitorious

    I do not plan to open a google code project, as I already have the gitorious project. But I agree that the issue tracker is a need … I don’t kown if there is something out there compatible with gitorious and free of charges 🙂 I’ll have to take a look and see what can be done.

    Any help is, of course, welcome on any of these tasks or any other that you can see.


  9. Joe
    November 1, 2010 at 23:19

    Nico (sorry, I’ll get your name write from now on :D) – one simple solution for issue tracking might be to migrate from gitorious to github. Github has a built in issue tracker and wiki.

  10. Joe
    November 1, 2010 at 23:20

    s/write/right/ ;D

  11. Joe
    December 20, 2010 at 20:01

    Nico, do you have any plans to add your project to the maven central repo? If you need help with this I would be more than happy to give you a hand (I’ve just gone through the process myself).

    I’d like to use your validator in my own project but at the moment my only sensible option seems to be to import your source. My project is ASL 2.0 too so I’m not concerned about licensing.

  12. jane
    January 4, 2011 at 04:05

    I have a lot of interest I took a look at your current implementation. It seems that it doesn’t provide a facility for me to plug in validators for custom types. json-schema.org says “If the property is not defined or is not in this list, then any type of value is acceptable. Other type values MAY be used for custom purposes …”
    In JacksonSchema.java, line 136 – ” Class clazz = (Class) Class.forName(“eu.vahlas.json.schema.impl.validators.” + className);
    “, is it possible to be enhanced to make it pluggable? Your code could have default type and validator mapping, and we can overwrite the map through some APIs.
    How does it sound to you?


  13. ken
    February 20, 2011 at 07:18

    Thx for implementing JSON schema in Java!

    I have built your library. The car.json test (JSONSchemaTest) fails. I suspect the car schema has changed since you ran your test. The test asserts there should be 4 errors but there are 9:
    $.adr.description: is missing and it is not optional
    $.adr.properties: is missing and it is not optional
    $.adr.type: is missing and it is not optional
    $.geo.description: is missing and it is not optional
    $.geo.properties: is missing and it is not optional
    $.geo.type: is missing and it is not optional
    $.email: string found, object expected
    $.email.value: is missing and it is not optional
    $.email.type: is missing and it is not optional

    A few other suggestions:
    * The test shouldn’t depend on the order of errors in errors[].
    * validate() should return a Map of errors so they can be bound to form fields.
    * Include a snapshot of the car schema in your resources.
    * It would be nice to have a suite which runs all of the tests.
    * The format attribute should be implemented so dates/times can validate.
    * The API should be standardized w/ the IETF so a programmer can switch impls.
    * public JacksonSchemaProvider(ObjectMapper mapper) — Don’t require the mapper argument.

    Do you need some help?

    • Jeff
      March 30, 2011 at 23:58

      I see the same thing with card.json test. It appears, however, that the latest version of the Core Schema Definition has changed fairly dramatically. From the most recent changes log of draft-zyp-json-schema-03:

      * Replaced “optional” attribute with “required” attribute.
      * Replaced “maximumCanEqual” attribute with “exclusiveMaximum”
      * Replaced “minimumCanEqual” attribute with “exclusiveMinimum”
      * Replaced “requires” attribute with “dependencies” attribute.

      …among others. Is anyone working on updates?

      • joe
        August 30, 2011 at 14:51

        Jeff, you might be interesting in watching this new project:

        This new project was originally based on Nico’s validator but has been developed further and supports (most of) the latest draft.

  14. Alex
    March 20, 2011 at 01:33

    Hey Nico,

    i tried the schema validator, there some bugs in there as it doesn´t validate description anymore… Any chance you are still workin on it?


  1. No trackbacks yet.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: