An enumeration is asked what it travels as by a way of its own, beside the form of every other type

This is design work that depends on #9, so wait for that first. Read the IsEnum checks at Wire.cs:299, Schemas.cs:50 and EnumerationSchemaFilter.cs:33, then JsonSerializerOptionsSerializer.GetValueForm and TypeDescriptors.GetConverters. Done means the shape carries the words or numbers of an enumeration and the IsEnum checks are gone, which needs maintainer agreement on the open questions first.

Description

What an enumeration travels as is asked by a way of its own, beside the one every other type is asked by: AddWord, IEnumerationSource, EnumerationValueForm, TravelsByName and GetValueForm on one side, Shape on the other. The same question — what does this look like written — has two answers that can part.

They already have. Four places look at IsEnum before they look at a declaration — Wire.Close (Wire.cs:299), Schemas.GetProjected (Schemas.cs:50), EnumerationSchemaFilter and the TypeNames of the client — so a form declared for an enumeration is not honoured. An enumeration a converter writes as an object, declared AsAnother so that it is described as what travels, is still described, bound and written into a client as an enumeration. And JsonSerializerOptionsSerializer.GetValueForm answers a value whose converter writes an object as an Integer holding the text of the object, since all it looks at is whether what was written starts with a quote.

Proposal

The form of an enumeration is a Shape

• Shape.AsText gains a closed list: the words a value can be written as.
• Shape.AsInteger, new, is a closed list of the numbers a value can be written as.
• A closed list excludes Pattern and Format, which say nothing of a value that can only be one of a list. So the int32 the filter of Swashbuckle writes for every enumeration by number, whatever the type under it, goes.
• A closed list is of any type, not only of an enumeration: an object written as one of three words, each read back by a constructor of its own, travels as a closed list as much as an enumeration does. So it is a list of words or of numbers, and not of members.
• Shape.OneOf admits AsInteger among its alternatives.

What an enumeration is when nothing is declared

Wire works it out by writing every value: words make an AsText, numbers an AsInteger. It is not AsText by default, because System.Text.Json writes an enumeration as its number unless a converter says otherwise, and a default of a text would describe a number as a word.

Values written as an object, or some as words and some as numbers, are refused, naming the enumeration and what it was written as, so that its form is declared: AsAnother for one written as an object, OneOf for one written in more than one form, or whatever fits what travels. A client is written for such an enumeration as for what it is declared, and not as a C# enum.

Which member is which word is worked out the same way, by writing each member, so that a client keeps the names of the members.

Asking the writer what it wrote

Working the form out needs to know, of each value, whether it came out as a word or as a number — which is what GetValueForm answers today with Word or Integer. The text alone does not say it: 71 is the number of one enumeration and the word of another. Nor can Wire, which supposes no format, look inside a text to tell that it is an object.

So the member of ISerializer that writes a value (#9) answers with one of two cases, in the vocabulary of the library and not of any format:

• a value written whole, with its ValueKind and its text;
• a value written with members, or as a list.

Each writer translates what it wrote into that: one of JSON by the token, one of XML by what it knows of the type it wrote.

What goes

• IsEnum leaves Wire.Close, Schemas, EnumerationSchemaFilter, TypeNames and the invariant of WireShape.OpenApi.Testing, which read the shape instead. It stays only where the values of an enumeration are listed to work its form out, since that is the one thing only the type answers.
• AddWord and IEnumerationSource stay, as ways of building the closed list of an AsText.
• TravelsByName, GetValueForm (of ISerializer and of Wire) and EnumerationValueForm go, the word or the number of each value being in the shape; and with them the fallbacks to the number of the member (Wire.cs:429, EnumerationSchemaFilter.cs:33), which answered a writer that did not know.
• Structure.Enumeration and EnumerationValue stay, made from the shape: they are what a client writes a C# enum from. For a closed list of a type that is not an enumeration, the names come from the words, as the names of the alternatives of a union do.

Questions

The binder of an enumeration nothing declares. TypeDescriptors.GetConverters teaches the types a wire declares, and an enumeration whose words only its converter knows is not declared. A route then reads it with the EnumConverter of .NET, which takes the name of a member or its number and not the word that travels (next-day). Proposed: one TypeDescriptionProvider registered for System.Enum, whose converter asks the wire when it converts, so that no list of assemblies is needed. Measured, it is the converter of every enumeration, including one made at run time in a collectible assembly of its own after the provider was registered, and of nothing that is not one. Not measured: whether ASP.NET has cached a binder before it is registered, and whether the cache of TypeDescriptor keeps a collectible assembly from being unloaded.

Two words that make the same name in a client — next-day and next_day both make NextDay. Proposed: refused, as two alternatives of a union nobody can tell apart are.

Expected Behavior

• An enumeration with nothing declared is an AsText when its values are written as words and an AsInteger when they are written as numbers.
• An enumeration written as an object, or in more than one form, is refused until its form is declared.
• An enumeration declared AsAnother or OneOf is described, bound and written into a client as what it is declared, and not as an enumeration.
• The schema of a closed list carries its words or its numbers and no format or pattern.
• A type that is not an enumeration can be declared with a closed list, and a client writes a C# enum for it.
• ISerializer has no member that answers only about an enumeration, and EnumerationValueForm is gone.

Depends on

#9, for the members of ISerializer that write and read a value.

Related

#10 checks a closed list against what is written, and needs the kind of what was written that this adds.