enumNames (v5 proposal) - sgpinkus/json-schema GitHub Wiki

THIS WIKI IS OBSOLETE. PLEASE SEE THE NEW JSON-SCHEMA-ORG/JSON-SCHEMA-SPEC REPOSITORY.

NOTE: This proposal has been migrated to https://github.com/json-schema-org/json-schema-spec/issues/57

Proposed keywords

  • enumNames

Purpose

Currently, enum values might be inscrutable, they might be meaningful in only one language, or they might be complex objects/arrays.

This keyword would provide short, meaningful names for each enum entry.

Values

The value of enumNames should be an array. The items in the array should be strings (or [multilingual objects](multilingual-meta-data-(v5-proposal)), if that makes it into the standard).

Behaviour

The names should be matched up to the enum options according to their positions in the respective arrays.

Example

{
    "enum": [
        "tri",
        "sq"
        "saw"
    ],
    "enumNames": [
        "triangle wave",
        "square wave",
        "sawtooth wave"
    ]
}

Concerns

Already covered by oneOf

You can express this (and more) using oneOf:

{
    "oneOf": [
        {"enum": ["value1"], "title": "Value #1"},
        {"enum": ["value2"], "title": "Value #2"}
    ]
}

It's actually not that much more verbose than enumNames, plus it would group the title/description/value in the same place.

Clunkiness

It seems a bit clunky to have this as a separate keyword, but it is important to not complicate the syntax for enum.

Other keywords

Are there any other keywords that need something like this? If we're doing it for enum, should we think about a human-readable description for pattern?

See also