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.
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:
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 |
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.
Thanks for your comments and for your post on your blog (http://www.cowtowncoder.com/blog/archives/2010/05/entry_398.html).
I am currently working on the possibility to reference other schemas first internally through the usage of the “$ref” property and then more generally with the Hyper Schema specification.
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!
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”]
and,
{ “p1” : “test object”, “p2” : 5 }
Hope this helps !
Cool, thanks Nico 😀
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:
http://jsontools.berlios.de/
Maybe efforts could be combined?
Hi,
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 !
Nico
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?
Apologies, I’ve just found the current implementation matrix @ src/test/resources/status.txt
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?
Hi,
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.
Nicolas
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.
s/write/right/ ;D
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.
Nico,
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?
Thanks,
Jane
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?
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”
attribute.
* Replaced “minimumCanEqual” attribute with “exclusiveMinimum”
attribute.
* Replaced “requires” attribute with “dependencies” attribute.
…among others. Is anyone working on updates?
Jeff, you might be interesting in watching this new project:
https://github.com/fge/json-schema-validator
This new project was originally based on Nico’s validator but has been developed further and supports (most of) the latest draft.
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?
Greetz,
Alex