[📝 Docs]: Improve Enum documentation

[benjagm]

What Docs changes are you proposing?

We received this feedback from the website and we think this is a great suggestion to improve our docs:

Page: /understanding-json-schema/reference/enum
Comment: It'd be nice to see enum defined in context - where does it live in an overall schema?

Code of Conduct

• I agree to follow this project's Code of Conduct

[Adity20]

Can I work on this one @benjagm

[gregsdennis]

Let's discuss what the improvement is in this issue before working on it.

[Adity20]

I guess telling the user where does enum live in overall schema using an example of enumerated values and then giving an example of using two different data types will be helpful.
In current json schema components we are showing the enum property only and not how it can be implemented withing overall schema

[gregsdennis]

where does enum live in overall schema

This is my point: where would you say that enum "lives" in a schema? There's not a correct answer to this because it depends on the data you're trying to validate.

enum on it's own in a schema, as it's shown in the current page, is perfectly valid and actually encouraged.

[Adity20]

Agreed @gregsdennis it can vary depending on different schemas

[Adity20]

It's fine as it is or we can just add an example for an array of enumerated values
{
"type": "array",
"items": {
"type": "string",
"enum": ["one", "two", "three"]
}
}
like this

[gregsdennis]

We shouldn't combine enum with other validation keywords (like type). enum lists valid values. Other validations are redundant.

We tell people this all the time, and they still do it. But we shouldn't promote this practice.

[Adity20]

Completely agree with you @gregsdennis.
So I guess we should leave it like that only to avoid any further confusion

[benjagm]

We just received more feedback regarding improving the docs of Enum:

• Comment: Is "enum" a keyword or a user-defined name? For example, would "color": ["red", "green", "blue"] work?

[Adity20]

So what changes we should introduce in the documentation @benjagm ?
color is a property of the object and enum specifies the value of color so the value must be one of the three strings.
I don't think "color": ["red", "green", "blue"] will work because we can't substitute color for enum keyword.
Let me know if I'm wrong @benjagm and @gregsdennis.

[gregsdennis]

I don't think that makes sense from a JSON Schema perspective.

However, I think it might make sense if they're trying to build a form, and they want a field called color to be one of those three values. However, I'd expect a form generator to understand "color": { "enum": [ "red", "green", "blue" ]}.

[Adity20]

Yeah agreed @gregsdennis
So we should add this to the enum documentation?

[gregsdennis]

Add what? We can't document any form gen stuff because every form generator does things differently. There's no standard.

[Adity20]

Comment: Is "enum" a keyword or a user-defined name? For example, would "color": ["red", "green", "blue"] work?

This comment

[gregsdennis]

I don't understand how adding that improves the docs.

[gregsdennis]

I think the docs are actually quite clear that it's a keyword. The examples on the page use it as a keyword. JSON Schema is comprised of keywords. I'm not sure how else it can be interpreted. I don't know what the commenter means by "user-defined name" because there's no such thing in JSON Schema. There are custom keywords, but those are also keywords.

The page STARTS with "The enum keyword..."

[rishabhsdev]

After going through this thread, I came up with a couple suggestions:

1. To further enrich the enum documentation:

We can add required constraint to the docs.

{
  "type": "object",
  "properties": {
    "color": {
      "enum": ["red", "blue", "green"]
    },
    "shape": {
      "enum": ["circle", "square", "triangle"]
    }
  },
  "required": ["color", "shape"]
}

Also, I agree with @gregsdennis , using type with enum is redundant, because we are already specifying valid values in enum, that's kind of the purpose of enum.

2. In response to the comment received Is "enum" a keyword or a user-defined name? For example, would "color": ["red", "green", "blue"] work?

It seems like a common query beginners might have. The code above perfectly shows how to use enum with a custom field. But if we want to answer this query explicitly, we can add "custom_key": { "enum": ["value1", "value2", "value3"] } to the documentation.

@benjagm Let me know if this task can be Assigned to me. Thanks.

[radhesh1]

is this free?

[gregsdennis]

@radhesh1 what needs doing is unclear. I don't think that anything needs to be done and this issue can be closed. If you see a way to make things more clear, please make a proposal here before creating a PR.