Show comments of JSON Schema in Documentation

[andreas-hilti]

The comments that are part of the JSON schema are not shown in the documentation. Can they be added?

Example:
refType has a comment

"$comment": "value SHOULD not start with the BOM-Link intro 'urn:cdx:'"

specification/schema/bom-1.5.schema.json

Lines 123 to 128 in 299209a

	"refType": {
	"description": "Identifier for referable and therefore interlink-able elements.",
	"type": "string",
	"minLength": 1,
	"$comment": "value SHOULD not start with the BOM-Link intro 'urn:cdx:'"
	},

However, this does not show up in the documentation:
https://cyclonedx.org/docs/1.5/json/#metadata_component_bom-ref

[andreas-hilti]

This is similar in spirit to #273.

[jkowalleck]

Current JSON docs generator in insufficient to do so, according to coveooss/json-schema-for-humans#198

[jkowalleck]

What you are referring to is a comment by me, the author. This is nothing relevant for documentation, so I thought at the time I wrote it.

The fact that the "value SHOULD not start with the BOM-Link intro 'urn:cdx:'" was stated, because it was a note for readers of the schema, in case they needed it for deeper understanding of the background of the change i made via 626dbbc
It was a comment for the future times when CycloneDX 2.0 would be written, when breaking changes would be allowed - when we would add regex-constraints to that element.

It is a mere comment, like

specification/schema/bom-1.5.schema.json

Line 139 in 299209a

"$comment": "part of the pattern is based on `bom.serialNumber`'s pattern"

If you feel this comment has more value, I'd suggest you pullrequest a change and put this $comment into the description.

[andreas-hilti]

Thanks, @jkowalleck. In my opinion, there are two aspects:

• (I learned that) $comment should contain only information for schema maintainers, not for the users, compare https://json-schema.org/understanding-json-schema/reference/comments (in agreement with your statement).
  Nevertheless, I would see some value if $comments were available, as it is also about maintaining the json schema. But let's see what comes out of Add an option to show $comments in generated docs coveooss/json-schema-for-humans#198
• A comment like "value SHOULD not start with the BOM-Link intro 'urn:cdx:'" is directed to the users, thus it would probably be better suited in the description.

I can open a PR.

[jkowalleck]

I can open a PR.

please do 👍
If this note is moved into the description, the $comment would simply be something like "TODO (breaking change): add a format constraint, that prevents the value from staring with urn:cdx:'" or something like this.

[jkowalleck]

all work done. enhancement was merged to 1.6