Restructure JSON enum documentation

[stevespringett]

Since JSON Schema does not allow enum values to be documented, the JSON Schema project recommends using oneOf/anyOf combined with an object with a const and description. This approach, while it does work, breaks most documentation tools that assume a choice like that has limited options, verses a list of enums with a lot more options to choose from. IMO, this is a workaround that does not address the core issue that the enum support in JSON schema has serious design issues.

To work around this issue, Adobe devises a simple way using a meta:enum property to document the enums and their descriptions. Support for meta:enum can be found at https://github.com/adobe/jsonschema2md and is additionally supported by other open source and commercial tools. The approach is briefly discussed here: https://stackoverflow.com/questions/64233370/in-json-schema-how-to-define-an-enum-with-description-of-each-elements-in-the-e

Currently CycloneDX overloads the description field with a long list of enum descriptions. It's an ugly approach since JSON does not support line breaks, and in using this approach, it makes merging and identifying diffs very difficult, since everything is on a single line of text.

Proposal

Refactor enum support in JSON to use meta:enum. This will greatly improve readability of the schema, our ability to maintain accurate descriptions, and our ability to diff/merge changes over time.

I have made a simple change to json-schema-for-humans which adds support for meta:enum and plan to contribute those changes back to the community.

An actual implementation looks like this:

"executionEnvironment": {
    "type": "string",
    "title": "Execution Environment",
    "description": "The target and execution environment in which the algorithm is implemented in.",
    "enum": [
        "softwarePlainRAM",
        "softwareEncryptedRAM",
        "softwareTEE",
        "hardware",
        "other",
        "unknown"
    ],
    "meta:enum": {
        "softwarePlainRAM": "A software implementation running in plain unencrypted RAM.",
        "softwareEncryptedRAM": "A software implementation running in encrypted RAM.",
        "softwareTEE": "A software implementation running in a trusted execution environment.",
        "hardware": "A hardware implementation.",
        "other": "Another implementation environment.",
        "unknown": "The execution environment is not known."
    }
}

When implemented, and with the changes I've made to json-schema-for-humans, the resulting documentation looks like this:

This approach will also help with TC54 documentation which must be purely human readable. We would be able to create a simple table with enum choice and descriptions which would be applicable to markdown and PDF output.