Operations with enums in request models should not accept integers as valid input

[hggutvik]

Description of the bug

We tag enums with [JsonConverter(typeof(JsonStringEnumConverter))] to get them stringified on serialization to JSON. While this does work as intended, it seems that the JsonStringEnumConverter doesn't automatically correct or invalidate integers on deserialization. Its default setting is to allow int values.
Here are the operations that use JsonStringEnumConverter for deserializing request data:

POST .../verification/verify (AddressType)
POST .../verification/send (AddressType)
PUT .../users/current/profilesettings (Language)
PATCH .../users/current/profilesettings (Language)

Steps To Reproduce

In any of the API operations listed above, pass an integer value to JSON fields that internally maps to enum.

Expected behavior: 400 Bad data as response
Actual behavior: successful response or internal server error because the integer was treated as valid input

Solution considerations

Current codebase state

We currently have two groups of enums in the codebase:

Group 1 — enums that already serialize as string

Language, AddressType (verification), VerificationType, ProfileType

Group 2 — currently serialized as integers:

UserType (UserType.cs) has no attribute and explicit numeric values 0–6. It's serialized in UserProfile.UserType (UserProfile.cs:59), which is returned by all the GET user endpoints, the internal lookup, contact-point lookups, etc. Today consumers get "userType": 1.
PartyTypeName (third-party contract, from Altinn.Register.Contracts), also in UserProfile, also serializes as an integer today ("partyTypeName": 1)

Key questions to consider:

1. what should be the default for a new enum?

• Serialize to int when converting C# -> JSON, and accept int values when deserializing from JSON -> C# request model
  vs
• Serialize to string when converting C# -> JSON, and reject int values when deserializing from JSON -> C# request model

2. Where do we want to define the enum behavior?

• Config located centrally/globally in Program.cs AddJsonOptions
  vs
• Config scattered, targeted per-enum as annotations/tags (example: VerificationType)

[hggutvik]

Suggestion a. Register a default JsonStringEnumConverter(allowIntegerValues: false) globally in Program.cs AddJsonOptions

Make "string enums, integers rejected" the default for every enum in the API via one converter registered in AddJsonOptions, then explicitly pin the exceptions that must stay numeric (UserType, PartyType) with JsonNumberEnumConverter registered ahead of it. All enum policy lives in one Program.cs block, no attributes. The mental model: "There is one house rule for enums; the config block lists every deliberate exception." I.e., allowing integers in serialization and deserialization is opt-in.

A converter registered in AddJsonOptions governs both read (input validation) and write (response serialization). That is, a global JsonStringEnumConverter changes output too (serializing to JSON), not just input (deserializing from JSON to C# request model). It also only applies to enums that don't have their own [JsonConverter] attribute. How this affects the existing two enum groups:

Group 1 — enums that already serialize as string - zero output change (pure win). These have string attributes today, so a global converter produces identical output and we can delete their attributes

Group 2 — currently serialized as integers (breaking change) - these will need special handling in order to stay numeric in serialization.
Today consumers get e.g. "userType": 1. A global string converter flips that to "userType": "SSNIdentified" — a breaking response-contract change for the portal / other UserProfile consumers that expect integers. The same goes for PartyTypeName.

The fact that we use model contracts that we don't control directly (PartyTypeName from Altinn.Register.Contracts) means that the int-allowing exceptions of Group 2 also need to be configured centrally in AddJsonOptions. This is because the type definition for PartyTypeName does not exist in our codebase (but in Register), so we cannot add the annotation tag for JsonNumberEnumConverter on it.

Pros:

• Gives the better end state, considering that our goal is to have only string enums that reject integers. Having the general rule defined as a single central config is clean and it makes the "house rule" clear. It promotes consistency across the whole API, as any new enums in the future will default to using the desired converter). Meanwhile, the few exceptions (group 2 enums ☝️) will be tagged/associated with JsonNumberEnumConverter.

Cons:

• has a blast radius of potentially breaking legacy numeric enums that we are unaware of
  -> extra care and/or testing effort must be taken to ensure that all Group 2 cases are added as exceptions in AddJsonOptions
  (note comment below - these really should be the only exceptions)

Suggestion b. Targeted converters for Language + AddressType to fix the input validation concern, leave response serialization untouched.

Fix only the enums we've identified as needing input validation (Language, AddressType), leave everything else exactly as it serializes today. The mechanism is per-enum (either a [JsonConverter] attribute with a small custom subclass, or a type-specific converter registered in options). The mental model: "Enums keep their current behavior; we override individually where we've decided integers must be rejected."
I.e., rejecting integers in serialization and deserialization is opt-out.

Pros:

• We don't touch 'legacy' enums, only those that we active want to change
  Cons:
• brings confusion to the codebase. The undesirable enum behavior becomes the general rule that applies in the codebase when enums are left as-is (i.e. when lacking targeted converters), while the developer has to "opt-out" of this to set the desirable enum behavior (serialize as string in responses, don't accept integers in requests) per new enum-instance

[hggutvik]

I used Claude to do an audit for checking all enum types, and the conclusion is that the only Group 2 exceptions are indeed the two we already have noted in UserProfile: UserProfile.UserType and UserProfile.Party.PartyTypeName

My opinion is that we should follow suggestion a. - seems like the best solution, and the confidence is high in that we have covered the relevant types.