Nicolas Vahlas's Blog

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.

Usage

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 ) {
			System.out.println(s);
		}

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