provide inline documentation for the schema

[jgadsden]

It is good to have the existing descriptions of the schema in the readme, but could the descriptions be included in the OTM schema itself? for example the Threat Dragon schema has inline descriptions such as:

        "id": {
          "description": "A unique identifier for this main threat model object",
          "type": "integer",
          "minimum": 0
        },

[jgadsden]

@dantolin-iriusrisk this would make the schema self documenting, but it would also increase the line count

[dantolin-iriusrisk]

@jgadsden It could be interesting, although, as you said, it would increase the file's size a lot, and it would create two sources of truth for the standard (the readme and the schema itself). I'll check this with the internal team to get their opinion. Anyway, apart from the completeness of the file, have you found any extra advantage in having the description in the schema (some doc generation tool able to read it, for example)?

[jgadsden]

that's a good point, perhaps there are auto-docs for schemas? the advantage from Threat Dragon point of view is that we did not need to remember to change the documentation when the schema was updated

[dantolin-iriusrisk]

I think it can be a good point, but, as this duplicates the sources of truth for the standard and we are now starting to collaborate to improve it, we think it is better to wait a bit more and, at the moment we are actually integrating with Threat Dragon, we can take the definitions and move them to the schema.

[jgadsden]

yes, agreed @dantolin-iriusrisk , and this issue can be closed