[📝 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.