Documentation

[alexvoss]

Dear @pwall567,

thanks for this very useful tool (and its sibling projects!).

I note from your comments on another issue that a rewrite is in progress. What I am wondering is if you could add documentation to the public methods?

Most are fairly self-explanatory but after a day of using the library I already stumbled across a question where documentation would have been helpful but I need to try and understand the way the code works.

Would love to help but I guess the initial move to document needs to come from the author.

Cheers, Alex

[alexvoss]

An example of what I am struggling with is the validateDetailed() method. I would love to know what it is meant to do. From the fields I guessed that I might be able to use it to debug cases where the validation succeeds when it should not. However, the result I get for a successful validation simply contains "Validation successful" in the annotation field and error, errors, and annotations are all null.

[pwall567]

Hi Alex, I recognise that the documentation for some of my libraries, this one included, is somewhat lacking. As you have noted, there is a new version in development and I would prefer to put my energy into that, but I accept that in the meantime, a little more documentation on the existing library would be helpful. I'll see what I can do in that regard.

In the meantime, perhaps I can explain about the validate, validateBasic and validateDetailed functions. The intention here was to provide provide output in the formats specified in the Output section of the JSON Schema specification.

That section lists four forms of validation. My implementation attempts to cover these as follows:

• Flag – the validate function returns a Boolean only
• Basic – the validateBasic function returns an Output object which (I hope) meets the specification in the document as closely as possible
• Detailed – the validateDetailed function returns an Output object that I realise is only a poor approximation of the format specified in the document
• Verbose – this form is not implemented

The specification is difficult to interpret in this area, and it provides only limited examples of the output expected. I am attempting to provide complete implementations of all four forms of output in the new version, but in the meantime, I'm hoping that the validate and validateBasic functions will suffice for most users.

(At this point I should note that "Verbose" output is probably what would assist with the case you describe in your second comment.)

I'm pleased to hear that you find the libraries useful, and I hope the current lack of documentation does not hold you back too much.

Regards, Peter

[alexvoss]

Dear Peter,

thanks for this. I have managed to get the YAML support in VSCode working, so now have another way of checking whether my schema works as intended (somewhat interactively, though I need to reload every time the schema changes). That means the need for json-kotlin-schema to help with that part is not as urgent anymore.

Let me know if there is anything I can do such as giving feedback. I will be working on this for the next few days and if I come across any other issues will try to send you useful reports.

Best wishes, Alex