Repository navigation
feat: add numerical enum generation support - #8532
Hardik K (hardikkaurani) wants to merge 4 commits into
Conversation
|
Hi Vincent Biret (@baywet), following your architectural feedback on microsoft/kiota-dotnet#843 regarding generator-first support for numerical enums, this PR updates the Kiota generator pipeline (OpenAPI schema analysis, CodeDOM, and language writers) to support numerical enums and resolves #5165. Whenever you have a moment, I'd appreciate your review and guidance on coordinating any downstream runtime changes. |
|
Thanks for opening this pull request! Please add a changelog entry under |
ff6a2af to
eea8ceb
Compare
|
Vincent Biret (@baywet) Please take a look into this. |
There was a problem hiding this comment.
🟡 Changes recommended
Unvalidated numeric enum values can inject source code into generated SDKs, while fractional values, defaults, and flags can cause compilation failures or loss of wire values.
6 open issues
Handle numeric enum defaults in Java · New Avoid unsupported fractional enums in C# and Go · New Resolve C# numeric defaults by enum wire value · New Validate numeric enum values before emitting source code · New Keep Go numeric flags formatting and imports consistent · New Preserve fractional values in Python numeric enums · New
Review effort: Balanced
| x.GetValue<string>() is string value && | ||
| !string.IsNullOrEmpty(value)); // number and boolean enums are not supported | ||
| !string.IsNullOrEmpty(value)) || | ||
| x.GetValueKind() is JsonValueKind.Number); |
There was a problem hiding this comment.
Updated the Java constructor default emitter in \Java/CodeMethodWriter.cs\ to resolve the matching enum option and emit double-quoted string literals (e.g. \Status.forValue(\10)), matching the \ValuedEnum\ signature defined on the Java enum. Added a constructor default regression test in \CodeMethodWriterTests.cs.
| var isNumeric = schema.Type is JsonSchemaType.Integer or JsonSchemaType.Number | ||
| || (schema.Enum is { Count: > 0 } && schema.Enum.OfType<JsonValue>().All(static x => x.GetValueKind() is JsonValueKind.Number)); |
There was a problem hiding this comment.
Added RevertFractionalEnumsToPrimitives in CommonLanguageRefiner.cs and invoked it in CSharpRefiner.cs (loat/double) and GoRefiner.cs (loat32/loat64) to downgrade non-integral enums back to primitive types before emission. Additionally guarded both CSharp/CodeEnumWriter.cs and Go/CodeEnumWriter.cs to reject fractional enums with descriptive exceptions if encountered directly, backed by refiner and writer unit tests.
| { | ||
| Name = declarationName, | ||
| Flags = enumFlagsExtension?.IsFlags ?? false, | ||
| IsNumeric = isNumeric, |
There was a problem hiding this comment.
Updated CSharp/CodeMethodWriter.cs to resolve default values against the enum's options matching by SerializationName, WireName, or Name. This ensures customized option names (such as those populated via x-ms-enum) are properly selected instead of re-cleaning the raw numeric literal. Added unit tests for default value resolution in constructor emission.
| writer.WriteLine($"{option.Name.ToFirstCharacterUpperCase()}{(codeElement.Flags ? " = " + GetEnumFlag(idx) : string.Empty)},"); | ||
| if (codeElement.IsNumeric) | ||
| { | ||
| writer.WriteLine($"{option.Name.ToFirstCharacterUpperCase()} = {option.SerializationName},"); |
There was a problem hiding this comment.
Added IsNumericEnum() validation in OpenApiSchemaExtensions.cs to require that all enum values are valid numbers before flagging the schema as a numeric enum. In addition, added strict numeric literal parsing across all target writers (C#, Go, Python, TypeScript, PHP, and Ruby) to reject non-numeric or hostile payloads prior to emission, along with hostile-payload regression tests for each writer.
|
|
||
| writer.WriteLine(); // gofmt: exactly one blank line before each top-level declaration | ||
| if (isMultiValue) | ||
| if (codeElement.IsNumeric) |
There was a problem hiding this comment.
Scoped the math import in GoRefiner.cs to non-numeric flags enums (enum.Flags && !@enum.IsNumeric), preventing unused import compiler errors. In Go/CodeEnumWriter.cs, implemented slice iteration over defined flag options in String() to support composite flag values (e.g. 1 | 2) cleanly without needing math.Pow. Covered with Go refiner and writer unit tests.
| writer.WriteLine("from enum import Enum"); | ||
| writer.WriteLine(); | ||
| writer.WriteLine($"class {codeElement.Name}(str, Enum):"); | ||
| var baseType = codeElement.IsNumeric ? (string.Equals(codeElement.Format, "float", StringComparison.OrdinalIgnoreCase) || string.Equals(codeElement.Format, "double", StringComparison.OrdinalIgnoreCase) ? "float" : "int") : "str"; |
There was a problem hiding this comment.
Added IsFractional on CodeEnum to detect floating-point formats and options with fractional components, and updated Python/CodeEnumWriter.cs to inherit from loat, Enum whenever IsFractional is true. This preserves member identities and exact wire values without integer truncation. Added unit tests covering fractional enums with and without explicit format.
- Java defaults: format wire values as string literals for forValue(...) in CodeMethodWriter. - Fractional enums: revert to primitive floating types in C# and Go refiners, and throw in writers if encountered. - C# defaults: resolve enum default values by matching SerializationName, WireName, or Name. - Literal validation: validate numeric literals in C#, Go, Python, TypeScript, PHP, and Ruby writers to prevent code injection. - Go flags & math import: format numeric flags enums in Go without math.Pow and restrict math package import to non-numeric flags enums. - Python fractional enums: inherit from float, Enum when enum is fractional. - Tests & formatting: update MapsNumberEnumToDoubleTypeAsync for numeric enum return type, format all modified files with UTF-8 BOM, and add comprehensive unit tests. Signed-off-by: Hardik Kaurani <hardikkaurani1@gmail.com>
|
I've addressed all review feedback from Copilot and resolved the CI test failures:
Ready for review when you have a moment. |

Closes #5165
Problem
OpenAPI definitions frequently define numerical enums (e.g.,
type: integer,format: int32,enum: [10, 20, 30]or withx-ms-enumvalue mappings). Previously, Kiota's generator pipeline:OpenApiSchemaExtensions.IsEnumchecked onlyJsonValueKind.Stringwith an explicit comment// number and boolean enums are not supported), causing numeric enums to fall back to primitive integer types instead of creating strongly-typedCodeEnumdefinitions.IsNumericand numeric format representation onCodeEnumandCodeEnumOptionin the CodeDOM.iotain Go, sequential flag powers, or no value assignments in C#), which could not preserve non-contiguous, non-zero-based, or negative wire values. In Go, evaluating[i]on non-contiguous enum values resulted in runtime array index out-of-range panics.Root cause
OpenApiSchemaExtensions.IsEnum: Guarded against any schema whose enum entries were not string literals.CodeDOM:CodeEnumandCodeEnumOptionhad no property capturing whether the enum is numerical or preserving its numeric format (e.g.int64).Language Writers: Writers for C#, TypeScript, Python, Go, PHP, and Ruby emitted quotes or sequential positions instead of explicit numeric literal constants corresponding to their wire values.Implementation
OpenApiSchemaExtensions.IsEnumto acceptJsonValueKind.Numberin addition toJsonValueKind.String.IsNumericandFormatproperties toCodeEnumandIsNumerictoCodeEnumOption.KiotaBuilder.AddEnumDeclarationandSetEnumOptions, populatedIsNumericwhen the schema is an integer/number schema or contains numeric enum items, preserving the numeric wire value inSerializationName.CodeEnumWriter.cs): WhenIsNumericis true, emits explicit member values (Option = 10,) and appends underlying type suffixes for integer formats (e.g.: longforint64,: sbyte,: short, etc.), while preserving[EnumMember(Value = "...")].CodeConstantWriter.cs,CodeFunctionWriter.cs): Emits numeric literals inEnumObject(Option: 10,) allowing(typeof Enum)[keyof typeof Enum]to yield a numeric literal union. AddedWireNamefallback for enum default values.CodeEnumWriter.cs): Inherits from(int, Enum)(or(float, Enum)) and emits numeric literals (Option = 10,).CodeEnumWriter.cs): Emits explicit integer constants (OPTION_TYPE Type = 10,int64forint64format) and generates a safeswitch istatement inString()to prevent out-of-range slice access panics on non-contiguous values.CodeEnumWriter.cs): Emits integer class constants (public const OPTION = 10;).CodeEnumWriter.cs): Emits numeric values in frozen enum hash (Option: 10).Compatibility
IsNumericdefaults tofalse, retaining identical output across all language writers.type: stringwithenum: ['+1', '-1']) continue to be treated as string enums.Serialization & Runtime Follow-up
kiota-dotnet,kiota-typescript,kiota-python) currently require runtime library coordination as discussed inkiota-dotnetPR - fixes a bug where query parameters would be missing in go #843. This generator change establishes the prerequisite foundation across languages.Maintainer context
Addresses architectural feedback from Vincent Biret (@baywet) on
microsoft/kiota-dotnet#843:Tests
ParsesNumericalEnumInformationAsync: Verifiestype: integer, format: int32, enum: [10, 20, 30]generates aCodeEnumwithIsNumeric == true,Format == "int32", and correct options.ParsesNumericalEnumWithNegativeAndSparseValuesAsync: Verifies negative (-1), zero (0), and sparse non-contiguous (100) values withint64format.ParsesNumericalEnumWithXMsEnumNamesAsync: Verifiesx-ms-enumoption names and descriptions are preserved with numeric wire values.WritesNumericalEnumWithExplicitValues,WritesNumericalEnumWithInt64Format,WritesNumericalEnumWithNegativeValues.WritesNumericalEnum.WritesNumericalEnum.WritesNumericalEnum,WritesNumericalEnumWithInt64Format.WritesNumericalEnumAsync.WritesNumericalEnum.dotnet test ./tests/Kiota.Builder.Tests/Kiota.Builder.Tests.csproj --filter "FullyQualifiedName~NumericalEnum"(all 12 passed) and fullCodeEnumWriterTests(all 75 passed).