Support extracting Description from compiled schema
Closed this issue · 7 comments
schema annotations (title, description, default, readOnly, writeOnly, examples) are commonly used for documentation. they don't participate in document validation. In order to avoid memory, they are not included in compiled schema definition.
Could you explain the use case, why you need them...
That's fair. My use case is code generation. We use json schema to validate the transport payload of messages between micro services and when a golang service receives a message I want to be able to use strong typing rather than empty struct maps.
I was able to generate the code using this library but I was hoping to add docstrings based on json schema descriptions.
@santhosh-tekuri annotations are increasingly important in JSON Schema, and will become more so. While it's definitely fine to implement just validation (a formal process of annotation collection only really became defined in draft-07 and is getting refined for draft-08, but is not a required feature), pretty much every usage of JSON Schema beyond validation relies on it.
I assume that most implementations will either choose to optimize for validation or will provide full functionality including annotation collection. So perhaps just a clear statement as to which you intend this project to be in your README would help.
@maroux I understand that description can be used as doc strings in generated go structures. I am interested in your project. if it is open-source please share the link.
@handrews in my old project i used RAML in internet devices. these devices has less RAM. so i have to traverse compiled RAML and make all annotations nil, to reduce memory footprint. So I did not keep annotations in compiled schema.
I will add Compiler.ExtractAnnotations = true/false flag which defaults to false, so that developers who do not need annotations can still discard them in compiled schema.
@santhosh-tekuri I don't have it completed yet - still a WIP evaluating which json schema library makes most sense for this project. Seeing the difference between docstring vs no docstring its pretty clear that docstrings are a deal breaker for this particular use case.
I like the extract annotations suggestion.
json-schema-org/json-schema-spec#530 if you want to give feedback on the whole annotations collection process for the next draft.
wow, thanks for the quick update!