Skip to content

[csharp] Map unknown enum values to the unknown default member - #25331

Merged
wing328 merged 2 commits into
OpenAPITools:masterfrom
DocSpring:csharp-unknown-enum-default
Nov 20, 2026
Merged

wing328 merged 2 commits into
OpenAPITools:masterfrom
DocSpring:csharp-unknown-enum-default

Conversation

@ndbroadbent

@ndbroadbent ndbroadbent commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

With enumUnknownDefaultCase=true, the C# generator adds an UnknownDefaultOpenApi member to each enum. But FromString throws, and FromStringOrDefault returns null, for any value the enum doesn't list. The generichost JSON converters turn that null into a JsonException, so a response containing an enum value added to the API after the client was generated still fails to deserialize, which is what the option is meant to prevent.

This PR makes both methods return the unknown default member when the option is on, for inner enums (modelInnerEnum.mustache) and top-level enums (modelEnum.mustache). Java's fromValue already behaves this way. Without the option the output is unchanged.

Spec

openapi: 3.0.3
info: { title: repro, version: 1.0.0 }
paths: {}
components:
  schemas:
    Color:
      type: string
      enum: [red, green]
    Pet:
      type: object
      required: [status]
      properties:
        status: { type: string, enum: [available, sold] }
        mode: { type: string, nullable: true, enum: [auto, manual] }
        color: { $ref: '#/components/schemas/Color' }

-g csharp --library generichost --additional-properties=enumUnknownDefaultCase=true

Before

public static StatusEnum? StatusEnumFromStringOrDefault(string value)
{
    if (value.Equals("available"))
        return StatusEnum.Available;

    if (value.Equals("sold"))
        return StatusEnum.Sold;

    if (value.Equals("unknown_default_open_api"))
        return StatusEnum.UnknownDefaultOpenApi;

    return null;
}

{"status":"pending"}, {"status":"sold","mode":"scheduled"} and {"status":"sold","color":"blue"} all throw JsonException: The JSON value could not be converted to ....

After

    if (value.Equals("unknown_default_open_api"))
        return StatusEnum.UnknownDefaultOpenApi;

    // Unknown values map to the unknown default member
    return StatusEnum.UnknownDefaultOpenApi;
}

The same three inputs deserialize with Status, Mode and Color set to UnknownDefaultOpenApi. Known values and "mode": null behave as before.

Testing

  • ./mvnw -DskipTests -pl modules/openapi-generator-cli -am package
  • ./bin/generate-samples.sh bin/configs/csharp-*.yaml (80 configs): no changes, because no C# sample config sets enumUnknownDefaultCase.
  • Added CSharpClientCodegenTest#testGenericHostEnumUnknownDefaultCaseMapsUnknownValues, covering an inner and a top-level enum. It fails without the template change and passes with it. CSharpClientCodegenTest: 24 tests, 0 failures.
  • Generated a net8.0 client from the spec above and deserialized the inputs above with the .NET 9 SDK, before and after.

PR checklist

  • Read the contribution guidelines.
  • Run the following to build the project and update samples:
    ./mvnw clean package || exit
    ./bin/generate-samples.sh ./bin/configs/*.yaml || exit
    ./bin/utils/export_docs_generators.sh || exit
    
    (For Windows users, please run the script in WSL)
    Commit all changed files.
    This is important, as CI jobs will verify all generator outputs of your HEAD commit as it would merge with master.
    These must match the expectations made by your contribution.
    You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example ./bin/generate-samples.sh bin/configs/java*.
    IMPORTANT: Do NOT purge/delete any folders/files (e.g. tests) when regenerating the samples as manually written tests may be removed.
    (Ran the build and regenerated all csharp-* configs; nothing changed. Not all configs.)
  • If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request.

@mandrean @shibayan @Blackclaws @lucamazzanti @devhl-labs


Summary by cubic

Fixes C# enum deserialization when enumUnknownDefaultCase=true so unknown values map to the generated UnknownDefaultOpenApi member instead of causing a JsonException.

FromString and FromStringOrDefault now return the unknown default member for any unrecognized value on both inner and top-level enums, matching Java's fromValue. Behavior is unchanged when the option is off.

  • Updated CSharpClientCodegenTest so the test fails if either method ends with anything other than returning the unknown default member.

Written for commit 7ed313d. Summary will update on new commits.

View guided diff

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 3 files

Reply with feedback, questions, or to request a fix.

View guided diff | Re-trigger cubic

@devhl-labs

Copy link
Copy Markdown
Contributor

Please merge once passing. A lot of times the first enumeration option is unknown, I think I'd like to see that used instead of injecting our own entry, but that's out of scope for your change here. Thanks for the fix.

@wing328

wing328 commented Nov 17, 2026

Copy link
Copy Markdown
Member

please resolve the merge conflicts when you've time and i'll try to get it merged before the upcoming release (due later this week)

@wing328 wing328 added this to the 7.28.0 milestone Nov 17, 2026
With enumUnknownDefaultCase, the generator adds an UnknownDefaultOpenApi
member to each enum, but FromString threw and FromStringOrDefault
returned null for any value the enum doesn't list. The generichost JSON
converters turn that null into a JsonException, so a response with a
new enum value still failed to deserialize.

Return the unknown default member from both methods when the option is
on, for inner and top-level enums, as Java's fromValue does. Without
the option nothing changes.
@ndbroadbent
ndbroadbent force-pushed the csharp-unknown-enum-default branch from 143efb7 to 9118df8 Compare November 19, 2026 21:26
Match each of FromString and FromStringOrDefault up to its closing brace,
so the test fails if either method ends any other way, such as
FromStringOrDefault returning null.
@ndbroadbent
ndbroadbent force-pushed the csharp-unknown-enum-default branch from 9118df8 to 7ed313d Compare November 19, 2026 22:46
@wing328
wing328 merged commit 7e8f514 into OpenAPITools:master Nov 20, 2026
15 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants