Add support for meta:enum

[stevespringett]

JSON Schema does not allow enum values to be documented. The project recommends using oneOf/anyOf combined with an object with a const and description as a workaround. This is documented here. 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. This method was originally proposed by the JSON Schema authors themselves as a possible solution. 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 some schemas overload 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

Add meta:enum support so that simple enum values (typically strings) can be easily documented.

An actual implementation looks like this:

"someProperty": {
    "type": "string",
    "enum": [
        "choice-1",
        "choice-2",
        "choice-3"
    ],
    "meta:enum": {
        "choice-1": "Description of Choice #1.",
        "choice-2": "Description of Choice #2.",
        "choice-3": "Description of Choice #3."
    }
}

When implemented, the generated Javascript documentation can look like this:

If implemented in the markdown templates, this could result in a table with two columns, one for the enum value and another for the description, such as:

Enum value	Description
choice-1	Description of Choice 1.
choice-2	Description of Choice 2.
choice-3	Description of Choice 3.

[dblanchette]

PR merged and released, thanks!

[dlenskiSB]

I've been looking for documentation on this feature, and great to see it merged!

It might be worth mentioning some already-existing real-world use of this feature :-)

• https://github.com/adobe/jsonschema2md examples and test fixtures of meta:enum (https://github.com/adobe/jsonschema2md/blob/487d089d9b84827fdff033af83779fcb49be3818/test/fixtures/enums/enums.schema.json#L1-L29)
• A real-world JSON Schema that makes extensive use of meta:enum (https://github.com/CycloneDX/specification/blob/master/schema/bom-1.6.schema.json#L1551-L1567):

      "type": {
        "type": "string",
        "enum": [
          "unofficial",
          "monkey",
          "backport",
          "cherry-pick"
        ],
        "meta:enum": {
          "unofficial": "A patch which is not developed by the creators or maintainers of the software being patched. Refer to [https://en.wikipedia.org/wiki/Unofficial_patch](https://en.wikipedia.org/wiki/Unofficial_patch).",
          "monkey": "A patch which dynamically modifies runtime behavior. Refer to [https://en.wikipedia.org/wiki/Monkey_patch](https://en.wikipedia.org/wiki/Monkey_patch).",
          "backport": "A patch which takes code from a newer version of the software and applies it to older versions of the same software. Refer to [https://en.wikipedia.org/wiki/Backporting](https://en.wikipedia.org/wiki/Backporting).",
          "cherry-pick": "A patch created by selectively applying commits from other versions or branches of the same software."
        },
        "title": "Patch Type",
        "description": "Specifies the purpose for the patch including the resolution of defects, security issues, or new behavior or functionality."
      },