Discussion on: RFC: JSONx Framework

Hi Jan,

If I understand correctly (and correct me if I'm wrong): you're looking for a way to associate documentation to the constituent parts of a JSON Schema. This was supported in an earlier revision of the JSON Schema Definition spec. I removed it to reduce the overall complexity of the JSD spec, so as to help myself more easily solve other problems I was working on. But now that you mention it, I'm realizing that I had left it out. And, in fact, it absolutely needs to be brought back (because in my own documentation I advertise the JSD's ability to "to describe constraints and document the meaning, usage and relationships of the constituent parts of JSON documents". So, thank you for bringing this to my attention.

If you would not mind, could I ask you to open an issue requesting this ability to "document constituent parts of a schema"? The effort needed to re-integrate document(ability) into the JSD spec is small. As per "generating documentation from the JSD spec," I believe that the .jsd form of the schema, with the addition of a doc property, would naturally fit the documentation requirement. Another approach would be to use the .jsdx form of the schema, and implement a simple XSLT file that would transform the .jsdx into an txt file or an HTML file to only show the object/property names and the documentation. An issue would be very appreciated. As I'm sure you're very well aware, I'm actively trying to bring attention to JSONx, and to get it into the hands of developers.

Regarding your second question: testing. Yes, now I understand what you are referring to. I had not thought of such a concept as you're describing, but I'm realizing that the test suite that I mentioned in my previous reply can be used to test user-defined schemas also. Specifically, look at the RuntimeTest. This class contains test methods that target testing of individual objects defined in datatype.jsdx. The RuntimeTest references the generated Java class bindings directly. The same concept can be applied to any other .jsd or .jsdx schema. You can use the generate goal of the jsonx-maven-plugin to generate the binding classes, and then create your own variation of RuntimeTest to test the individual object definitions.

I really like this concept actually, and think it would be very beneficial for users as a feature of itself. It would be very cool if any schema could be fully tested just by specifying a .jsd or .jsdx file as an input into a new goal (named "regression-test" or something) in the jsonx-maven-plugin. This way, every build of one's application would assert proper functioning of JSONx for the specified schema. If you're up for it, a feature request in issues would be highly appreciated!