metosin/malli

Feature request: enum value descriptions

Open

#613 opened on Jan 10, 2022

View on GitHubContributor guide
 (1 comment) (0 reactions) (0 assignees)Clojure (237 forks)batch import
enhancementhelp wanted

Repository metrics

Stars
 (1,724 stars)
PR merge metrics
 (No merged PRs in 30d)

Description

Sometimes, the enumerated values are not clear enough by themselves. It would be nice to have a standard way to provide a description for each enumerated value.

Following our discussion on Slack, a nice solution would be to have :enumn (similar to :catn) that support description of enumerated values, like this:

[:enumn 
   ["foo" {:description "foo means that you don't know how to name things"}] 
   ["bar"] 
   "baz"]

Where some enumerated values have description and some don't.

Open question

Is there a way to pass the description of enumerated values to Swagger? JSON Schema doesn't seem to support description for enumerated values.

Contributor guide

Research direction
Explore how existing enum like schemas (e.g., `:enum`, `:catn`) are defined in the malli codebase. Then implement a new `:enumn` variant that accepts maps with optional `:description` keys. Also investigate how to extend Swagger/JSON Schema generation to include descriptions for enum values.
Tech stack
None
Domain
api
Issue type
Feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
Half day
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
ClojureGit
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
65