Can a per-enum documentation value be supported by this library?

[ddcruver]

It would be useful to allow the schema to define JavaDocs for each enumeration value.

Possible Implementation:

{
  "$id": "https://example.com/schemas/math/Digit.schema.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "string",
  "javaType": "com.example.api.math.Digit",
  "description": "All the digits.",
  "enum": [
    "Zero",
    "One",
    "Two",
    "Three",
    "Four",
    "Five",
    "Six",
    "Seven",
    "Eight",
    "Nine"
  ],
  "enumDescriptions": {
    "Zero": "No digit.",
    "One": "The first digit",
    "Two": "The second digit",
    "Three": "The second digit",
    "Four": "...",
    "Five": "...",
    "Six": "...",
    "Seven": "...",
    "Eight": "...",
    "Nine": "..."
  },
  "required": [],
  "definitions": {},
  "additionalProperties": false
}

package com.example.api.math;

import java.util.HashMap;
import java.util.Map;
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonValue;

/** All The Digits */
public enum Digit {

    /** No digit. */
    ZERO("Zero"),

    /** Thre first digit. */
    ONE("One"),

    /** This second digit. */
    TWO("Two"),

    /** This third digit. */
    THREE("Three"),

    /** ... */
    FOUR("Four"),

    /** ... */
    FIVE("Five"),

    /** ... */
    SIX("Six"),

    /** ... */
    SEVEN("Seven"),

    /** ... */
    EIGHT("Eight"),

    /** ... */
    NINE("Nine");

    private final String value;
    private final static Map<String, Digit> CONSTANTS = new HashMap<String, Digit>();

    static {
        for (Digit c: values()) {
            CONSTANTS.put(c.value, c);
        }
    }

    private Digit(String value) {
        this.value = value;
    }

    @Override
    public String toString() {
        return this.value;
    }

    @JsonValue
    public String value() {
        return this.value;
    }

    @JsonCreator
    public static Digit fromValue(String value) {
        Digit constant = CONSTANTS.get(value);
        if (constant == null) {
            throw new IllegalArgumentException(value);
        } else {
            return constant;
        }
    }

}

Since this is a generated class it would also possibly to store it and add a function to get it at runtime, but that may be feature creep.

[joelittlejohn]

It's interesting that this is actually a gap in JSON Schema. You can't add a description on an enum value, so you can't include something that jsonschema2pojo could use.

One problem here is that JSON keys can only be strings, so your enumDescriptions map can only provide descriptions when the enum values are strings 🤔

[ddcruver]

Can the enum keys (value) be something besides strings?

[ddcruver]

Ohh ok, the spec supports enums of different types but it looks like this library will convert them to Strings.

• null values are ignored
• numbers are converted to string

[ddcruver]

One problem here is that JSON keys can only be strings, so your enumDescriptions map can only provide descriptions when the enum values are strings 🤔

I would say it is safe to limit the implementation to objects of type "string" and add a warning if someone wants to create an enum of a different type.

[ddcruver]

Looking at the json-schema project it looks like this issue was in discussed json-schema-org/json-schema-spec#57 but it was ultimately dropped and other options were pursued.

One thing is we could add an "extension" to implement it or see if oneOf is a good choice for implement enumerations with descriptions.

But that would imply that #831 would need to be implemented or https://github.com/joelittlejohn/jsonschema2pojo/wiki/Proposal-for-allOf,-anyOf-and-oneOf.

The above examples though are using a type of object but in my case it would be a string so it could be simply implemented as an java enumeration instead of alternative fields like described in https://github.com/joelittlejohn/jsonschema2pojo/wiki/Proposal-for-allOf,-anyOf-and-oneOf.

[ddcruver]

Looking at my original examples something like this may make more sense if we went down the "extension" route.

{
  "$id": "https://example.com/schemas/math/Digit.schema.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "string",
  "javaType": "com.example.api.math.Digit",
  "description": "All the digits.",
  "enum": [
    "Zero",
    "One",
    "Two",
    "Three",
    "Four",
    "Five",
    "Six",
    "Seven",
    "Eight",
    "Nine"
  ],
  "jsonSchema2Pojo-enumExtended": [
    {"enum": "Zero", "description": "No digit."},
    {"enum": "One", "description":"The first digit"},
    {"enum": "Two", "description":"The second digit"},
    {"enum": "Three", "description": "The second digit"},
    {"enum": "Four", "description": "..."},
    {"enum": "Five", "description": "..."},
    {"enum": "...", "description": "..."}
  ],
  "required": [],
  "definitions": {},
  "additionalProperties": false
}

[joelittlejohn]

Does the new proposed JSON schema vocabulary for UIs have an anything to say about this? It looks like the issue you linked to was closed in favour of a whole new vocabulary for UIs, so did they ended up including anything there that we should adopt?

[ddcruver]

Does the new proposed JSON schema vocabulary for UIs have an anything to say about this? It looks like the issue you linked to was closed in favour of a whole new vocabulary for UIs, so did they ended up including anything there that we should adopt?

I believe they are going to use the following method for now: json-schema-org/json-schema-spec#57 (comment)

But when it comes to the UI vocabulary I believe the discussions are still in their initial stages.

I am a little unclear because in one place they talk about it being a way to make a set of restrictions on the schema based on rules (https://github.com/json-schema-org/json-schema-spec/issues/683) and other places they talk about adding additional keywords json-schema-org/json-schema-vocabularies#2. The support for vocabularies might not even be in v8 and might be deferred to a later version.

[ddcruver]

@joelittlejohn I am all in for just closing this issue and just focusing on the implementation defined in #1035 if you agree.

[joelittlejohn]

Yes, I agree. I think that's a good proposal 👍