7.3.2 Documentation

[lvdbrink]

7.3.2 leaves it open whether documentation is or is not included when present in the UML file and describes that in some cases it's better to leave documentation out.

Shouldn't we then say that it is recommended to leave documentation out of the JSON Schema?

And/or have a TV to control whether to include or exclude it from the JSON Schema.

[cportele]

I would say that the information whether or not to include documentation is not something to encode in the model. It will depend on how the schema is going to be used. One might even want to have both variants. Without documentation for validation (smaller schema documents) and with documentation for other purposes where humans interact with the schema.

In my view, whether or not to include it is mainly a parameter for the encoding process and it is not something where a recommendation can be made one way or the other.

[jechterhoff]

7.3.2 allows (all or pieces of) documentation from the application schema to be encoded in JSON Schema, but does not state any requirements on how exactly the encoding has to look like. We do not recommend to leave documentation out of the JSON Schema (we just give potential reasons for why that may be benefitial).

Maybe we can make this more clear by defining an explicit "Permission" (to include documentation using JSON Schema annotations), like in section 7.11?

[PalmJanssen]

I would say that no change is needed.

[lvdbrink]

I would say that no change is needed.

I'm fine with that.